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Preface 


This manual describes the features, uses, constructs, and syntax of the 
VAX RPG II programming language on VAX/VMS systems. 


Structure of This Document 


This manual contains 16 chapters and 3 appendixes. 


Chapter 1 explains the VAX RPG II logic cycle. 


Chapter 2 explains how to use the VAX RPG II editor to create and 
edit RPG II programs. 


Chapter 3 explains how to compile, link, and run programs. 
Chapter 4 explains the format of a listing file. 


Chapter 5 explains how to use the VAX/VMS Debugger to debug VAX 
RPG II programs. 


Chapter 6 explains how to perform screen activities with VAX RPG II 
programs. 


Chapter 7 explains how to use VAX RPG II indicators. 

Chapter 8 explains how to manage files. 

Chapter 9 explains those elements that affect printer output files. 
Chapter 10 explains how to create and access tables. 

Chapter 11 explains how to create and access arrays. 


Chapter 12 explains how to use the VAX RPG II CALL interface to 
access VAX/VMS Run-Time Library procedures, system services, and _ 
subprograms. 


Chapter 13 explains how to improve the efficiency of programs. 
Chapter 14 explains VAX RPG II elements and data types. 

Chapter 15 lists specifications, allowable entries, and their functions. 
Chapter 16 explains how to use VAX RPG II operation codes. 
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Appendix A lists the VAX RPG II character sets. 


Appendix B explains the differences between VAX RPG II and PDP-11 
RPG Il. 


Appendix C shows the VAX Performance Coverage Analyzer applied 
to a VAX RPG II program. 


Intended Audience 


This manual is intended for use by programmers familiar with computer 
programming fundamentals and the RPG II language. It is designed to be 
used both as a reference manual and as a user’s guide. 


Conventions Used in This Document 


Conventions Meaning . 
| The VAX RPG II editor cursor is represented by a box. 
[] Brackets enclose an optional portion of a format. 


{ } Braces enclose a mandatory portion of a format. 


A vertical ellipsis indicates that not all of the program lines 
in an example are shown. 


$ SHOW TIME Command examples show all output lines or prompting: 


05-AUG-1986 characters that the system prints or displays in black letters. 
11:55:22 All user-entered commands are shown in red letters. 


Associated Documents 


If you need additional information on VAX /VMS you should refer to the 
following manuals: 

e VAX/VMS Debugger Reference Manual 

° VAX/VMS Linker Reference Manual 

¢ VAX/VMS Librarian Reference Manual 
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VAX/VMS Run-Time Library Routines Reference Manual 
VAX/VMS System Services Reference Manual 

VAX/VMS Utility Routines Reference Manual 

VAX/VMS System Manager's Reference Manual 
VAX/VMS Record Management Services Reference Manual 
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Developing VAX RPG II Programs on VMS 


This part of the manual provides information on the devel- 
opment of VAX RPG Il programs: 

Creating the source 

Using the VAX RPG II editor 

Compiling, linking, and running the program 
Interpreting a VAX RPG II compiler listing 

Using the VAX/VMS Debugger 


Chapter 1 


Understanding the VAX RPG Il Logic Cycle 





VAX RPG II is a language processor that provides a convenient and effi- 
cient means of preparing a wide variety of reports as well as performing 
other commercial data processing tasks. VAX RPG II is an extended imple- 
mentation of the RPG II language that was developed by IBM; it includes 
DIGITAL extensions for integration with the VAX/VMS architecture. VAX 
RPG II runs on the VAX/VMS or MicroVMS operating system and con- 
sists of a compiler, special editor, run-time support, conversion utility for 
existing screen definitions, and sample programs showing use of VAX RPG 
II in screen handling applications. 


VAX RPG II is a nonprocedural language; that is, every program compiled 
by the VAX RPG II compiler executes according to a fixed plan. Unlike a 
procedural language such as COBOL, the logic of this plan is not supplied 
by the programmer, but is built into the compiler. This built-in logic 

is called the VAX RPG II logic cycle. The execution of a VAX RPG II 
program consists of a number of iterations of the logic cycle. 


You provide directions to the program using VAX RPG II specifications. 
Specifications are the record-oriented instructions by which you define 
input and output formats, arithmetic processes, and special operations to 
be performed depending on the data input and desired output. There are 
seven different specification types. Each specification is structured in an 
80-column format; the columns are grouped into fields according to the 
purpose of the specification. You choose a specification according to the 
program function you wish to do and supply input in the fields according 
to the specific application. See Chapter 15 for an explanation of each 
specification. The VAX RPG II specifications you include determine what 
happens within the various phases of the logic cycle, but do not change 
the basic sequence of program execution. 
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For example, you can write an Input specification to program VAX 

RPG II to recognize and process a particular input file record type; you 
cannot program VAX RPG II to read three input records in a row, print a 
report heading, load a table, write four different output records, and then 
perform total calculations. This series of steps, while perfectly acceptable 
in a COBOL program, does not fit into the structure of the VAX RPG II 
logic cycle. 


The VAX RPG II fixed logic cycle was designed specifically to accom- 
modate the sequence of operations needed to generate most common 
business reports and file maintenance functions. However, the fixed na- 
ture of the VAX RPG II logic cycle does not prevent you from controlling 
the set of functions performed for each input record and, to some extent, 
the sequence and timing of these functions. This control is provided by 
the use of indicators. For example, by setting various indicators on or off 
when certain conditions occur, you can affect the sequence of program 
execution within the phases of the normal logic cycle. See Chapter 7 for 
more information on indicators. Therefore, to write effective VAX RPG II 
specifications and to take advantage of what flexibility and control VAX 
RPG II does provide, you must thoroughly understand the structure and 
timing characteristics of the overall VAX RPG II logic cycle, and recognize 
both VAX RPG II’s special capabilities and its limitations. 


There are 10 fundamental operations that are performed during the 
operation (and reiterations) of the VAX RPG II logic cycle, as shown in 
Figure 1-1 and identified in the accompanying keyed list. 
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Figure 1-1: Logical Flow of the VAX RPG Il Logic Cycle 





FIRST CYCLE 
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Key to Figure 1-1: 


In the FIRST CYCLE, several initialization tasks are accomplished. Files 
are opened, the local data area is loaded, the system date is obtained from 
the system, and counters, tables, and arrays are initialized. The program 
then transits into the NORMAL CYCLE. 


When the NORMAL CYCLE is entered, program instruction lines 
with special conditions for Output specifications are processed. 


All control-level and record-identifying indicators are set off. 


A record is read, and the appropriate record-identifying indicator is 
set on. 


If the control field of the record just read is different from the control 
field of the previous record, a control break occurs. When a control 
break does occur, the appropriate control-level indicator is set on, plus 
all lower control-level indicators. 


© If VAX RPG II detects that this is the first iteration after the FIRST 


iS ee. 


CYCLE, it branches to step 8. 


Total calculations (conditioned by control: level indicators in the 
Calculation specifications) are processed if the appropriate control- 
level indicators are on. 


If totals are requested in the program, the program does total output 
operations. 


If the last-record indicator is on, the LAST CYCLE is entered and the 
program ends. 


Detail calculations and program output are processed from data read 
in this cycle. 


All remaining detail calculations are processed on the data from 


the current record read at the beginning of the NORMAL CYCLE. 
Then, the cycle continues around, repeating while there are records to 
process. 


Upon detecting the last-record indicator, the program enters the LAST 
CYCLE, does one-time cleanup work including total calculations and total 
output operations, and the program ends. 
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1.1 The VAX RPG Il General Logical Sequence 


Every VAX RPG II program follows the same sequence of execution steps 
which form the general or normal logic cycle. Some of the programs 
you write will require you to use one or more of the additional operations 
of VAX RPG II: matching fields (described in Section 8.11, chaining (de- 
scribed in Section 16.7.1), overflow processing (described in Section 9.3.2), 
and look-ahead processing (described in Section 15.6.8). Each of these 
additional operations executes according to the fixed logic cycle within the 
general logical sequence of the program. These functions are discussed 
later in this chapter. 


The VAX RPG II logic cycle is executed once for each input record. The 
logic cycle consists of the following three steps, performed in order for 
each record: . 


1. Inputting a record 
2. Performing calculations 
3. Outputting one or more records 


Each logic cycle begins when a new record is input and ends just before 
the next record is input. The VAX RPG II specifications you develop 
determine the range and type of specific functions performed during each 
phase. During the calculation and output steps within each cycle, there 
are two distinct timing phases: 


¢ Total time—operations are performed on summary data accumulated 
from a group of related records. 


¢ Detail time—operations are performed on individual records. 


Sections 1.4.1 and 1.4.2 describe total-time and detail-time characteristics 
and operations. 


The first and last iterations of the VAX RPG II logic cycle are somewhat 
different from all other iterations. Sections 1.2 and 1.3 describe these 
differences and explain how you can take advantage of them. 
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1.2 The First Cycle 


When program execution begins and before the first input record is read, 
several one-time-only operations are performed, which constitutes the 
first cycle. You can exert control over this process by providing detail- 
time output records conditioned by the first-page (1P) indicator, and by 
using Output specifications with either no conditioning indicators or with 
all negative conditioning indicators. (See Chapter 7 for more details on 
conditioning indicators.) During the first cycle, VAX RPG II performs the 
following initialization operations: 


e Obtains the current (system) date UDArE UDAY, UMONTH, and 
UYEAR (see Chapter 9). 

¢ Loads the local data area. 

¢ Opens all files (see Chapters 6 and 8). 

e Loads preexecution-time tables and arrays (see Chapters 10 and 11). 

e Initializes page number counters. 


e Prints heading and detail lines conditioned by the 1P indicator, by all 
negative indicators other than the 1P indicator, and by no indicators. 


Although all iterations of the logic cycle (other than the first) include a 
total-time phase, VAX RPG II bypasses all total-time calculations and 
total-time steps during the first cycle unless the last-record (LR) indicator 
is on. This behavior, like the logic cycle, is built into VAX RPG II. 


After initialization tasks are performed, VAX RPG II reads the first record 
in the primary file, if used, and then reads the first record in each sec- 
ondary file, if used, and determines the type of each record read. (The 
distinction between primary, secondary, and demand files is complex and 
is discussed in Chapters 6 and 15.) 
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1.3 The Last Cycle 


The last cycle is performed after all the records you specified for pro- 
cessing have been read from all primary and secondary files. When the 
last record from the last file has been read, VAX RPG II sets on the LR 
indicator and all the control-level indicators (L1 through L9). Then, after 
this last record has been processed, VAX RPG II performs the following 
operations: 


e Performs total-time calculations. 
¢ Writes total-time output. 


¢ Outputs any tables or arrays that have output files associated with 
them. 


¢ Closes all files. (Some files are left to be closed automatically by the 
VAX Record Management System (VAX RMS) when the program ends 
execution.) 


e Outputs the local data area. 
e Ends program execution. 


1.4 A Normal Cycle 


A normal cycle (sometimes referred to as the general cycle) in a VAX 
RPG II program can be defined as any cycle but the first or the last. 
During a normal cycle, VAX RPG II performs all operations necessary to 
process a single input record. Because of the nature of most VAX RPG 
II applications, a normal program cycle includes two special phases— 
total-time and detail-time. Total time occurs before detail time because 
detail time is for the previous record. When the first record is read, there 
is no previous record; hence there is no detail time. Note that the cycle 
is a closed loop. In a normal cycle, VAX RPG II performs the following 
sequence of steps: 


1. Outputs heading lines, if specified 

Outputs detail-time information pertaining to the previous record 
Reads an input record 

Performs total-time calculations for the previous record, if required 


Woe wo 


Performs total-time output 
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6. Checks the LR indicator; if it is on, VAX RPG II terminates the 
program (see Section 1.3) 


7. Processes the record read in step 3; performs all detail-time 
calculations 


Steps 4 and 5 constitute total time; steps 1, 2, and 7 constitute detail time. 


This list of steps in a normal cycle is an overview only. Figure 1- 2 isa 
detailed flowchart of a normal VAX RPG II logic cycle. 


1.4.1 Total Time 


During total time, VAX RPG II checks which control-level indicators (L1 
through L9) you have defined and the control field you have associated 
with each. (See Chapter 7 for details on using control-level indicators.) 
For example, if your application involves the generation of a monthly 
sales report, you may have associated indicator L9 with the grand total 
of monthly sales, indicator L8 with total sales by region, indicator L7 
with total sales by district office, and indicator L6 with total sales by 
salesperson. This is shown in the following example: 


he length 
Control level Decimal positions 
| IHalf adjust (H) 
VI 


: 
| Indicators Operation | 
1 | | | IlResulting 
1 | Factor | Factor Result! Jlindicators 
1 | i | 2 field | Il+- 0 
Cl NxxNxxNxx I | | | 1 Ils < = +- Comments --+ 










0) | 4 2 | 3 | 4 | 4) | 6 | a | 
123456 7830123456 7830123456 7890123456 7890123456 7890123456 789012345678901254567890 









HX * % Po ae eS 
CL9 MONTH MULT 12 GRAND 
CL8 REGION ADD REGION TOTREG 
CL? DIST ADD DIST TOTDIS 
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If during a particular cycle VAX RPG II determines that the salesperson 
identification number in the record just read is different from the sales- 
person number in the previous record, a control break occurs at the 
salesperson total level. At this control break, your program outputs the 
accumulated total sales for the salesperson whose number was found in 
the previous record. 


1-8 Understanding the VAX RPG Il Logic Cycle 


You might print each person’s name and sales total on a separate line. Or, 
you might choose to print a page heading (with a date), and then print 

a salesperson’s total sales, thus providing a separate one-page report for 
each salesperson. The Output and Calculation specifications you develop 
determine the contents, order, and appearance of your report. 


During another cycle, it might be determined that the region identifier of 
the record just read is different from the region number in the previous 
record. Given the control-level indicators described in the preceding 
example (L9, L8, L7, L6), this means that a three-level control break has 
occurred. In this situation, you must first output the accumulated total for 
an individual salesperson (L6), then the accumulated total for a district 
office (L7) and, finally, the accumulated total for the region (L8). 


Similarly, after the last input record in the file is read, a four-level control 

break occurs automatically. At that point, your program must first output 

the accumulated total for the last individual salesperson in the last district 
office (L6); then, the accumulated total for the last district office (L7); then, 
the accumulated total for the last region (L8); and, finally, the accumulated 
grand total of all sales for the month (L9). 


After all control breaks have occurred, total time ends and detail time 
begins. Detail-time operations are for the record just read. 


1.4.2 Detail Time 


- During detail time, your program performs operations specific to each 
individual record. In the example described in Section 1.4.1, each time a 
record is read, the detail-time operations might consist of the following 
steps: 


1. Printing an output line on your report. For example, each record in 
your file might contain a weekly sales figure for a particular salesper- 
son. The report would list the week’s beginning and ending dates and 
the sales figure. 


2. Adding the sales figure to all active accumulators. Then, when the 
next control break occurs, each accumulator will contain the correct 
amount. 


3. Performing any other operations you defined in your =pacilieadons 
These might include moving data fields and handling errors. 


Figure 1-2 is a detailed flowchart of a complete, normal VAX RPG II pro- 
gram cycle. Each processing and decision box is numbered; the numbers 
are keyed to the annotations that immediately follow the figure. 
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Figure 1-2: Detailed VAX RPG Il Logic Cycle Flowchart 





1. First cycle 


Get date if UDATE, UDAY, UMONTH, or UYEAR used. 
Load pre-execution-time tables and arrays. 


Open all files. 





2. Beginning of norma! cycle 


*DETL 
Perform heading, detail, and fetched overflow output. 
Set 1P indicator off. 


Overflow 
routine. 





3. *GETIN 













Any hait 
indicators 
on? 


yes 


Terminate 
program. 





Set off control-level and any record-identifying 
indicators. 

Set off overflow indicators unless they were set on 
during detail-time calculation or output operations 
of previous cycle. 


















5. 
LR yes 
indicator 
on? 
6 no 
Primary no 
file 
specified? 
7 yes 





Read input record from the last file processed, if 
required. (Not required for input files with 
look-ahead fields, or on the first cycle). 

For the first cycle, read and determine record type 
and sequence of the first record in all primary and 
secondary files. 










(Continued on next page) 
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Figure 1-2 (Cont.): Detailed VAX RPG II Logic Cycle 
Fiowchart 





yes 






Determine record type and check sequence. 


Determine which file to process. 

lf a FORCE operation was specified, use unless 
the file is at its EOF. 

If no FORCE operation was specified, call the 
matching field routine. 


Matching 
fietd routine. 





11. 


Should LR yes 
indicator 
be on? 


Set on the record-identifying indicator 
for the selected record. 
















13. 
Has a 
control no 
break 
occurred? 
14. yes 


Save contents of the control fields. 





(Continued on next page) 
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Figure 1-2 (Cont.): Detailed VAX RPG Il Logic Cycle 
Flowchart 











Set on control-level indicators, 
as required. 







16. 





“ Should 
total-time 
calculations 

be done 
now? 





no 









*TOTC 
Perform total-time calculations. 












»*TOTL 
Perform total-time output and 
fetched overflow output. 






Overflow 
routine. 






19. 
Perform table and] : 
_ uR yes array output: close 
a files; terminate 
on! program. 
no 
20. 







Any 
overflow 
indicators 
on? 












+OFL 
Overflow routine. 






Perform overflow output. 








(Continued on next page) 
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Figure 1-2 (Cont.): Detailed VAX RPG Il Logic Cycle 
Flowchart 


Set MR indicator on or off, as required. 


Set off command key indicators 


Set on command key indicator corresponding to 
command key pressed. 


Extract data fields from the record to be processed. 
Set field-record-relation indicators on or off, as 
required. 





25. 






Look-ahead 
fields 
specified? 


no 







Perform look-ahead operation. 





*DETC 
Perform detail-time calculations. 


Return to the beginning of the normal cycle (step 2.). 
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Key to Figure 1-2: 


@ This step is executed only during the first cycle. It initializes your 
program for execution. Initialization consists of retrieving the date 
(if you specified UDATE, UDAY, UMONTH, or UYEAR), opening all 
files, and loading all preexecution-time tables and arrays. 


@ VAX RPG II writes heading and detail lines (identified by H or D in 
column 15 (Type) of the Output specification). Heading and detail 
lines are always executed at the same time. If conditioning indicators 
are specified, the conditions for the indicator must be satisfied. If 
the fetch overflow logic is specified and the overflow indicator is on, 
RPG II writes the appropriate overflow lines. If the 1P indicator is on 
(during the first cycle only), VAX RPG II prints all lines conditioned by 
it, then sets the 1P indicator off. VAX RPG II executes this step at the 
beginning of the program so that heading lines can be printed before 
processing begins. 


© VAX RPG II checks whether any halt indicators (H1 through H9) 
are on; if any are, the program terminates. If you do not want your 
program to terminate here, you must set all halt indicators off previous 
to this step. You can set halt indicators on, however, at any time 
during the program. 


© VAX RPG II sets control-level indicators (L1 through L9) and all 
indicators used as record-identifying indicators off. VAX RPG II also 
sets overflow indicators (OA through OG, and OV) off, unless they 
were set on during detail time (detail-time calculations or output 
operations) in the preceding cycle. All other types of indicators that 
are on remain on. 


@® Here, VAX RPG II determines whether the LR indicator is on. If it 
is, RPG II branches to step 15 and sets on control-level indicators L1 
through L9, if used. 


© VAX RPG II determines whether a primary file was specified by the 
program. If not, VAX RPG II proceeds directly to step 16. 


If required, VAX RPG II reads an input record from the last primary 
or secondary file processed. If this was an input file with look-ahead 
fields, the record is already available; therefore, no read operation may 
be necessary at this time. On the first cycle, a record is read from each 
primary and secondary file. 


VAX RPG II tests the file just read for end-of-file. If end-of-file has 
been encountered, the program bypasses step 9. 


If VAX RPG II reads a record from a file, the record type is determined 
and the record sequence is checked. If the record type cannot be 
determined, or the record is out of sequence, the program terminates. 


1-14 Understanding the VAX RPG I! Logic Cycle 


® In this step, VAX RPG II determines which file to process. If a FORCE 
operation was executed during the previous cycle, the forced file 
is selected for processing. (All records processed with a FORCE 
operation are processed with the matching-records (MR) indicator set 
off.) However, if the forced file is at end-of-file (EOF), the normal 
multifile logic selects the next record for processing. If no forced 
file was specified, VAX RPG II determines whether matching fields 
were specified. If so, the matching-fields routine is given control (see 
Figure 1-3). Otherwise, all records in a primary file are processed 
first, then the records from each secondary file in order of their 
specification. 

@ Here, VAX RPG II determines whether the LR indicator should be set 
on. The LR indicator is set on when the program has reached the end 
of all the files that you have specified for processing until the end-of- 
file, and when all the records from secondary files that match the last 
primary record have been processed. If the LR indicator should be set 
on, VAX RPG II branches to step 15 and sets on indicators L1 through 
L9. 


VAX RPG II sets on the record-identifying indicator for the re ord 
selected for processing. 


VAX RPG II determines whether the record selected for processing 
has caused a control break to occur. A control break occurs when the 
value in the control field of the record being processed differs from 
the previous value of the control field. See Section 1.4.1 for more 
information. 


If a control break has occurred, VAX RPG II saves the contents of all 
appropriate control fields. 


If a control break has occurred, VAX RPG II sets the appropriate 
control-level indicator (L1 through L9) on; at the same time, 

VAX RPG II sets all lower-level control-level indicators on. The L1 
through L9 indicators can be used for conditioning only if they have 
been defined as conditioning indicators. 


@ VAX RPG II determines whether total-time calculation and output 
operations should be performed. If control-level indicators are not 
specified in columns 59 and 60 (control-level) of the Input specifica- 
tion, VAX RPG II bypasses total-time calculation and output operations 
during the first cycle only; after the first cycle, VAX RPG II performs 
total-time calculation and output operations for every cycle. 


If control-level indicators are specified, VAX RPG II bypasses total- 
time calculation and output operations until after the first record with 
control fields is processed. When the LR indicator is on, VAX RPG II 
always performs total-time calculation and output operations. 
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® In this step, VAX RPG II performs all total-time calculations condi- 
tioned by a control-level indicator or containing LO in columns 7 and 
8 of the Calculation specification. Total-time calculations can include 
CHAIN operations, in which a record is immediately retrieved from 
an input file (see Figure 1-4), or READ operations, in which the next 
record is retrieved from a demand file. 


® Here, VAX RPG II writes all total-time output lines that satisfy the 
conditions specified by the indicators. If an overflow indicator (OA 
through OG, or OV) is on, and fetch overflow is specified, VAX RPG 
II writes the overflow lines as well. 


® VAX RPG II determines whether the LR indicator is on. If it is on, 
VAX RPG II performs table and array output, closes all files, and 
terminates the program. 


VAX RPG II checks to determine whether any overflow indicators (OA 
through OG, or OV) are on. 


If any overflow indicators are on, the overflow routine is given control 
(see Figure 1-5). VAX RPG II outputs all lines conditioned by those 
overflow indicators that are on. However, VAX RPG II outputs these 
lines only if they were not output by fetch overflow logic (step 2 or 
step 18). 


@ VAX RPG II determines whether the MR indicator should be set 
on. If this is a multifile program and the record being processed is 
a matching record, VAX RPG II sets the MR indicator on; it remains 
on for the duration of the cycle during which the matching record is 
processed. If these conditions are not present, VAX RPG II sets the 
MR indicator off. 


® If the program contains a WORKSTN file, VAX RPG II sets off the 
KA through KZ and KO through K9 indicators. If form input was 
terminated by a command key, VAX RPG II sets on the corresponding 
command key indicator. Note that if an error occurred on the read, 
the command key indicators are not changed. 
VAX RPG II extracts data fields from the record to be processed and 
sets the field indicators on or off, as appropriate, for those fields. 
VAX RPG II then determines whether look-ahead fields are specified 
in the last file processed and whether it is an input file. 
If the last file processed was an input file with look-ahead fields, VAX 
RPG II passes control to the VAX RPG II look-ahead routine (see 
Figure 1-6). In this routine, VAX RPG II retrieves the look-ahead 
record and extracts the look-ahead fields. If look-ahead fields are not 
specified, VAX RPG II continues with detail-time calculations 
(step 27). 
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@ This is the detail-time calculations step. Here, VAX RPG II performs 
all conditioned detail-time calculations and subroutines. The calcu- 
lations may include CHAIN and READ operations (see Figure 1-4). 
Detail-time calculations complete the VAX RPG II logic cycle. Then, 
the cycle branches to step 2 to begin again. 


1.5 VAX RPG II Detail Program Logic Cycle 


This section consists of annotated flowchart diagrams that show, in detail, 
various routines within the VAX RPG II logic cycle. The following figures 
are provided: 

e Figure 1-3 shows the VAX RPG II matching-fields routine. 


e Figure 1-4 shows VAX RPG II file processing for chained and demand 
files. 


e Figure 1-5 shows VAX RPG II overflow processing. 
e Figure 1-6 shows VAX RPG II look-ahead processing. 
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Figure 1-3: Logic Cycle for the Matching-Fields Routine 


Determine the file 
to be processed. 


Matching 


. . Issue a run-time 
fields in J 


error message. 


Move the matching fields 
to the temporary buffer. 


Return to program. 
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2) 


Key to Figure 1-3: 


VAX RPG II determines whether the program uses more than one pri- 
mary and secondary file. If multifile processing is in effect, processing 
continues with step 2. Otherwise, the program branches to step 3. 


VAX RPG II compares the matching fields to determine which file is 
to be processed. VAX RPG II extracts the matching fields and checks 
their sequence. — 


If the matching fields are not in sequence, a run-time error occurs and 
the program terminates. 


VAX RPG II moves the matching fields into a temporary buffer. The 
next record is selected, based on the value of the matching fields. 


@ VAX RPG II returns to the program. 
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Figure 1-4: Logic Cycle for Chained and Demand Files 


1. 
Retrieve the record. 


Record no 
found? 


Set on the record-identifying 
indicator. 
3. 


Extract the specified fields and 
set on field indicators, if used. 


4. 
Return to program. 





Resulting 
indicator 
specified? 














Issue a run-time error. 






Set on resulting indicator. 
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Key to Figure 1-4: 


@ VAX RPG II retrieves the next record in the file specified by the 
CHAIN or READ operation code. If the record is not found on a 
CHAIN operation or an end-of-file occurs during a READ operation 
and a resulting indicator is not specified, a run-time error occurs. If 
the record is not found on a CHAIN operation or an end-of-file occurs 
during a READ operation and a resulting indicator has been specified, 
the indicator is set on and control returns to the program. 


@ VAX RPG II sets on the record-identifying indicator associated with 
the chained or demand file for the record type read. 
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© VAX RPG II extracts the fields from the record just retrieved. Also, 
VAX RPG II sets on any field indicators associated with the record. 


@ VAX RPG II returns to the program. 


Figure 1-5: Logic Cycle for Overflow Processing 


1: 










Lines output 
with a previous 
fetch? 


yes 






Output lines conditioned 
by the overfiow indicator. 
Return to the program. 
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Key to Figure 1-5: 


@ VAX RPG II uses the fetch overflow routine to determine whether 
the overflow lines were written previously. If the overflow lines were 
written previously, the program branches to the specified return point; 
otherwise, it continues with step 2. 


VAX RPG II evaluates all overflow lines and writes those lines that 
satisfy the conditions of the indicators. 


VAX RPG II returns to the program. 
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Figure 1-6: Logic Cycle for Look-Ahead Processing 


1. 
Retrieve next record 
for this file. 










Set all look-ahead 
fields to Qs. 







2. 
Extract look-ahead 
fields. . 

3. 
Return to program. 
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Key to Figure 1-6: 


@ VAX RPG II reads the next record for the file being processed. If the 
end-of-file has been reached, all look-ahead fields are filled with 9s 
and control is returned to the program. 


@ VAX RPG II extracts the look-ahead fields from the record. 
© VAX RPG II returns to the program. 
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Chapter 2 


Using the VAX RPG Il Editor 





This chapter explains how to use the VAX RPG II editor to create, edit, 
and read (or view) VAX RPG II programs. 


The VAX RPG II editor is available on the VT100, VT200, and VK100 
(GIGI) terminals. 


The VAX RPG II editor allows overstriking; that is, you can change a 
program line by placing the cursor in the column where you want to make 
a change and typing a new character, without affecting any characters to 
the right of the cursor. 


The cursor is represented as a box (§) in the examples throughout this 
chapter. 


All examples in this chapter assume a terminal page size of 24 lines, 
unless otherwise noted. 


2.1 Qualifiers 


Invoke the VAX RPG II editor by typing the RPG/EDIT command. 
To create a file, provide a file specification, as shown in the following 
example: 


$ RPG/EDIT FIRSTTRY 
You do not have to supply the RPG file type, because it is the default. 


To edit or read a file, include the name of the file you want to edit or 
read when you invoke the VAX RPG II editor. See Section 2.8.2 for an 
example. 


Using the VAX RPG Il Editor 2-1 


The following error message may be displayed when you invoke the VAX 
RPG II editor: 


¥TPU-E-NONANSICRT, SYS$INPUT must be an ANSI CRT 


If this error occurs, leave the VAX RPG II editor and make sure that the 
VAX/VMS terminal characteristics are set properly for your terminal by 
typing the SET TERMINAL/INQUIRE command. 


When you invoke the VAX RPG II editor, if the number of columns 
(SET TERMINAL /WIDTH=m) i is less than 80 or the number of lines 
(SET TERMINAL/PAGE=n) is less than 6, the VAX RPG II editor will 
display the following message, then will exit: 


At least 6 lines and 80 columns on the screen are required 


See the VAX/VMS DCL Dictionary for information on the SET TERMINAL 
command. 


Note that the SET TERMINAL command must be entered before invoking 
the VAX RPG II editor. 


If you are using a VK100 (GIGI) terminal and the terminal screen does. 
not appear to update correctly, leave the VAX RPG II editor and type the 
SHOW TERMINAL command to make sure that the device is a VK100. If 
it is not, type the SET TERMINAL/INQUIRE command to make sure that 
the VAX/VMS terminal characteristics are set properly for your terminal. 


If the file you specify when invoking the VAX RPG II editor is a new file, 
the VAX RPG II editor displays the following message: 


File not found 


If the file you specify when invoking the VAX RPG II editor is an existing 
file, the VAX RPG II editor displays the following message: 


n lines read from file device: [directory] filename.type; version 
Finally, the VAX RPG II editor displays the following message: 
Press the PF2 key to get help information 


If the terminal page size is less than 17 lines, the initial HELP message is 
not displayed. If HELP is requested using the HELP key or a SET HELP 
command in a start-up command file, and the terminal page size is less 
than 17 lines, the following message is displayed and the usual HELP 
action will not be performed: 


. At least 17 lines on the screen are required by the editor to provide HELP 
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Table 2-1 lists the qualifiers that you can use with the RPG JEDIT com- 
mand. If you precede a qualifier with /NO, that qualifier is not in effect. 


Table 2-1: RPG/EDIT Command Qualifiers 


Qualifier Negative Form Default 

/COMMAND ~~~—~—~—~— /NOCOMMAND..—~—_ /COMMAND=RPGINI 
/CREATE /NOCREATE /CREATE 

/JOURNAL /NOJOURNAL /JOURNAL 

/OUTPUT /NOOUTPUT /OUTPUT 
/READ_ONLY /NOREAD_ONLY /NOREAD_ONLY 
/RECOVER /NORECOVER /NORECOVER 
/START_POSITION /NOSTART_POSITION /START_POSITION=(1,1) 


Sections 2.1.1 through 2.1.7 describe the qualifiers and their use. 


2.1.1 /COMMAND Qualifier | 
The /COMMAND qualifier causes the VAX RPG II editor to execute a 
specified file in the start-up command file. Its format is as follows: 
/COMMAND [=file-spec] | 


The VAX.RPG II editor reads commands from any file specified by 
the qualifier. Each command in the specified file is treated as if the 
/COMMAND qualifier were used. 


The / COMMAND qualifier is present by default, with a default value of 
RPGINI. If the /NOCOMMAND qualifier is used, then no command file 
is executed. See Section 2.7.2 for information on start-up command files. 
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2.1.2 /CREATE Qualifier 


The /CREATE qualifier creates a file for the editing session. If the 
specified file already exists, that file is opened. Its format is as follows: 


/CREATE 


The /CREATE qualifier is present by default. If the /NOCREATE qualifier 
is used, the file is not created. However, if the file already exists, it is 
opened. 


2.1.3 /JOURNAL Qualifier 


The /JOURNAL qualifier creates a journal file for the current editing 
session. Its format is as follows: 


/ JOURNAL [=file-spec] 


If you should leave an editing session abnormally, you can use the journal 
file to reexecute all the commands you issued during the session. To do 
this, type the RPG/EDIT/RECOVER command. | 


The /JOURNAL qualifier is present by default. If you do not provide a 
file specification with /JOURNAL, the VAX RPG II editor creates a journal 
file with the same name as your input file and the default file type JOU. 


2.1.4 /OUTPUT Qualifier 


The /OUTPUT qualifier defines the name of the output file. Its format is 
as follows: 


/OUTPUT [=file-spec] 


The /OUTPUT qualifier is the default. If you do not provide a file 
specification with /OUTPUT, the VAX RPG II editor creates an output file 
with the same node, device, directory, name, and type as the input file, 
whose version number is one higher than the highest existing version of 
the input file. 


If you use the /NOOUTPUT qualifier, the VAX RPG II editor does not 
create an output file. In this case, you must either use the QUIT command 
or specify a file specification with the EXIT command to leave the VAX 
RPG II editor. 
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2.1.5 /READ_ONLY Qualifier 


The /READ_ONLY qualifier tells the VAX RPG II editor not to create 
a journal file or an output file for the file you are currently editing. Its 
format is as follows: 


/READ_ONLY 


You can use the /READ_ONLY qualifier when you want to view a file 
without changing its contents. In this case, you must either use the QUIT 
command or specify a file specification with the EXIT command to leave 
the editor. 


The /NOREAD_ONLY qualifier is the default and automatically creates 
a journal file and output file for the file you are currently editing (unless 
you leave the VAX RPG II editor using the QUIT command). 


Using the /READ_ONLY qualifier has the same effect as using both the 
/NOOUTPUT and the /NOJOURNAL qualifiers with the RPG/EDIT 
command. 


2.1.6 /RECOVER Qualifier 


The /RECOVER qualifier reads the commands from a journal file and 
reexecutes all the edits you made during an editing session. Its format is 
as follows: 


/RECOVER 
When the recovery is done, the VAX RPG II editor responds with: 
Recovery complete 
_ At this time, you can continue editing your file. 


If the name of the recovery journal file is different from the default 

(the same file name as the input file with the JOU file type), use 
/JOURNAL=file-spec and /RECOVER to specify another name, as shown 
in the following example: 


$ RPG/EDIT/JOURNAL=FILE1 . JOU/RECOVER FILE2.RPG 


In this example, the journal file name is FILE1.JOU, and the name of both 
the input and output files is FILE2.RPG. If you do not use /JOURNAL, 
the journal file name is FILE2.JOU. 


The /NORECOVER qualifier is the default. 
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2.1.7. /START POSITION Qualifier 


The /START_POSITION qualifier determines where the VAX RPG II 
editor starts in the editing buffer. Its format is as follows: 


/START_POSITION (=(line,column)] 


The /START_POSITION qualifier i is the default. The setting is line 1, 
column 1. 


The /NOSTART_POSITION qualifier is equivalent to 
START_POSITION=(1,1). 


2.2 The Editor Screen 
The VAX RPG II editor screen consists of the following components: 
¢ The HELP window 
¢ An 80-column ruler 
e Tab stops 
e = The editing window 
e The prompt line 
e The message line 


Note that when you use a terminal without scrolling regions (for example, 
VK100 (GIGI)), the VAX RPG II editor must redisplay the information on 
the screen rather than scrolling new information onto the screen. 


The following screen shows an example of each of the VAX RPG II editor 
screen components. Note that all screens shown are based on a default _ 
setting of 24 lines for the page size with a top ruler. If you want to change 
the page size, see the SET TERM/PAGE commands in the VAX/VMS DCL 
Dictionary. 
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Hx input file with the shipment data for the past:'4 quarters. 
H#-- 


H 

FSHIPS IP F 4 DISE 
Search for: editor } 
String not found ' 


help window 


80-column 
ruler 


tab stops 


source window 


prompt line 


message line 
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When you use the HELP function (default = PF2), the HELP window 
appears on the screen. It includes a diagram of the keypad and other key 


functions. 


When the keypad diagram is displayed and you enter the HELP function 


again, the following message appears: 


Press the key for which you want further HELP information 


You can press the HELP key and any other key listed in the keypad 
diagram to display HELP information on that key in the HELP window. 


See Section 2.5.2 for an example. 
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The HELP_SPECS function (default = PF1/PF2!) causes the HELP window 
to display the specification format for the current line. See Section 2.5.3 
for an example. See the DISPLAY function, Section 2.5.11, for information 
on how to remove HELP from the screen. 


If you press CTRL/C while HELP information from the VAX RPG II 
editor HELP command is being written to the terminal, you must type a 
terminator to resume editing. 


If you do not request HELP information, the VAX RPG II editor displays 
the program in the entire screen except for the ruler and tab stops and the 
‘prompt and message lines, as shown in the following example: 


ee Re Te a EL an ee 





0 4 2 | 
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H* FUNCTIONAL DESCRIPTION: 
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H% products broken down by division and department using an 
H% input file with the shipment data for the past 4 quarters. 
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1 PF1/PF2 indicates that these two keys should be pressed in succession. 
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An 80-column ruler in reverse video is displayed above or below the 
source window. See Section 2.6.8.4 for information on setting the ruler. 
Below the ruler, a tab stop marks the beginning of each field for the 
specification of the current line. 


An asterisk (*) indicates a tab stop where you can enter a field value. A 
dot (.) indicates that the column must be left blank. A dash (-) after an 
asterisk indicates that the field must contain numeric data. Numeric data 
must be right-justified. Blanks after an asterisk indicate that the field must 
contain alphanumeric data. Alphanumeric data must be left-justified. 


The VAX RPG II editor marks the line after the last line in the editing 
buffer with the end-of-buffer [EOB] symbol. The [EOB] symbol will not 
appear in the output file. 


The last two lines of the screen consist of the prompt line and the message 
line. The prompt line displays prompts in reverse video for input when 
you use functions such as FIND and COMMAND. The message line 
displays informational and error messages. The following example shows 
what the VAX RPG II editor screen looks like with the specification 
format for the current line, the prompt for the FIND function, and an 
informational message. 
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Currency symbol 

Inverted print (DIJ) 

| Alternate collating sequence (SE) 

| | 

| | | 

| | | 
e | 3 | 4 | 5 


| 
| 
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| . 

| 
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He++ 
Hx FUNCTIONAL DESCRIPTION: 


He This program produces a report of shipments for various 
Hit products broken down by division and department using an 


He input file with the shipment data for the past 4 quarters. 
io ! be 
4 | 
FSHIPS IP F 41 DISK 
Search for: 









New mail ralammarelel= MYNODE from SYSTEM 
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2.3 The Cursor 


The VAX RPG II editor cursor is represented as a box (J) or an underscore 
(—), depending on the cursor setting for your terminal. The cursor is 
displayed in the current column on the current line. Note, however, that 
if the current column is column 81, the cursor is displayed in column 80 
on the current line. If you try to move the cursor to the right of column 
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81 or to the left of column 1, the current column remains unchanged and 
one of the following messages is displayed on the message line: 


Attempt to move past column 81 


Attempt to move before column 1 


2.4 The Buffers 


The VAX RPG II editor uses the following four buffers: 


Editing 


The editing buffer contains the file of source code that i is displayed on 
the VAX RPG II editor screen. 


Deleted-field 


The deleted-field buffer contains the field deleted when you use the 
DELETE_FIELD function (default = MINUS). See Section 2.5.14 for 
information on the DELETE—FIELD function. You can access the 
contents of the deleted-field buffer by using the UNDELETE_FIELD 
function. See Section 2.5.15 for information on the 
UNDELETE_FIELD function. 


Deleted-line 


The deleted-line buffer contains the line deleted by the 
DELETE_LINE function (default = PF4). See Section 2.5.6 for more 
information on the DELETE_LINE function. You can access the 
contents of the deleted-line buffer by pressing the UNDELETE—LINE 
function (default = PF1/PF4). See Section 2.5.7 for more information 
on the UNDELETE_LINE function. 


Paste 

The paste buffer contains the range of lines delimited by the 
SELECT (default = PERIOD) and CUT (default = KP6) functions 
(see Section 2.5.32). You can access the contents of the paste buffer 


by using the PASTE function (default = PF1/KP6). See Section 2.5.21 
for more information on the PASTE function. . 
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2.5 Keys and Functions 


To make sure the VAX RPG II editor is using the correct VAX/VMS 
terminal characteristics for your terminal, type the DCL command 
SET TERM/INQUIRE before invoking the VAX RPG II editor. The 
following diagram represents the VAX RPG II editor keypad: 


VT100/VT200/VK100(GIGI) Keypad _ VAX RPG II Editor Keypad 





ZK-1605-84 2K-5550-86 


This chapter refers to those keys with numbers and symbols as KPn, 
where KP means keypad and n is the number of the key shown on the 
VT100, VT200, and VK100 (GIGI) keypad. For example, KP6 refers to the 
keypad key numbered 6. Table 2-2 lists the name and default function of 
each key. 


Note that many keys have alternate functions. An alternate function 

is enabled when you press the GOLD key (default = PF1) followed by 
the key you want to use. This sequence is referred to in this chapter as 
PF1/[key_name]. 
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Table 2-2: VAX RPG Il Editor Define Key Defaults 


COMMAND 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY/GOLD 
DEFINE KEY 
DEFINE KEY/GOLD 
DEFINE KEY 
DEFINE KEY/GOLD 
DEFINE KEY 
DEFINE KEY/GOLD 
DEFINE KEY 
DEFINE KEY/GOLD 
DEFINE KEY 
DEFINE KEY/GOLD 
DEFINE KEY 
DEFINE KEY/GOLD 
DEFINE KEY 
DEFINE KEY/GOLD 
DEFINE KEY 
DEFINE KEY/GOLD 
DEFINE KEY 
DEFINE KEY/GOLD 
DEFINE KEY 
DEFINE KEY/GOLD 
DEFINE KEY 
DEFINE KEY 
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P 
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A 
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Oo © © 


A 
Ne) 


MH 


KP4 
KP4 
KP5 
KP5 
KP6 
KP6 


KP1 
KP2 


DEFAULT 


~ GOLD 


UP 
DOWN 

LEFT 

RIGHT 
HELP_KEYPAD 
HELP_SPECIFICATIONS 
FIND_NEXT 

FIND 
DELETE_LINE 
UNDELETE_LINE 
PAGE 

COMMAND 
SECTION 

DISPLAY 
REVIEW_ERROR 
MOVE_TO_RULER 
DELETE_FIELD 
UNDELETE_FIELD 
ADVANCE 
BOTTOM 

BACKUP 

TOP 

CUT 

PASTE 
SHIFT_LEFT 
SHIFT_RIGHT 
FIELD 
END_OF_LINE 
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Table 2-2 (Cont.): VAX RP 


COMMAND 


DEFINE KEY/GOLD 


DEFINE KEY 


DEFINE KEY/GOLD 


DEFINE KEY 
DEFINE KEY 


DEFINE KEY/GOLD 


DEFINE KEY 


DEFINE KEY/GOLD 


DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 
DEFINE KEY 


A 


A 


EY 
P2 
P3 
P3 
NTER 
PO 
PO 


El AAA 
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: = Z * 


CTR 
CTRL 
RETURN 
CTRL/R 


a] [a 
-} ja 
x] |x 
~~ = 
= ? 


Q 2 
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10 


bd ek 
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16 

IND 

INSERT HERE 
REMOVE 
SELECT 

PREV SCREEN 


NEXT SCREEN 
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Gil Editor Define Key Defaults. 


DEFAULT 


‘DELETE_TO_END_OF_LINE 


CHARACTER 
COLUMN | 

ENTER 

LINE 

OPEN_LINE 

SELECT 

RESET 
FIELD_BACKWARD 
FIELD_FORWARD 
NEW_LINE 
REFRESH_SCREEN 
DELETE_TO_BEGINNING_OF_LINE 
REFRESH_SCREEN 
EXIT 
DELETE_CHARACTER 
EXIT 
FIELD_BACKWARD 
HELP_KEYPAD 

ENTER 

FIND 

PASTE 

CUT 

SELECT 

SECTION BACKWARD 
SECTION_FORWARD 


See DEFINE KEY (Section 2.6.2) for a complete list of definable keys. 
Sections 2.5.10 through 2.5.44 describe these functions and explain how 
to use them. ce 


2.5.1 GOLD Function 


The GOLD function (default = PF1) enables you to select the alternate 
function of a key. In the following diagram of the keypad, the alternate 
key names appear in the shaded areas: 


VAX RPG II Editor Keypad 





2K-5550-86 


2.5.2 HELP_KEYPAD Function 


The HELP_KEYPAD function (default = PF2) displays the keypad “eg 
inthe HELP window, as shown in the following example. 
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PF1/PF2 - RPG II specification formats | +------- $------- $rennnn-te------ -+ 


Press the PFi/KP7 key and type HELP for | Gold | Help IFnx FndIDIL UdL | 
information on commands and functions. faa reae— feSsSrS= $a=SSenm toons — + 

For help on a specific key, press the IPag hei Dsp|Rev MovIDIF UdF | 
PF2 key followed by the key for which Prenee fener cee frosser- sce atarana + 

you want help information. pad Bot Bok Top! Cut Pas! Sh ShRI 

Other keys: BS_KEY DEL-KEY. i, Prete sten-s--= frase eestenssnne + 
TAB_KEY UP, DOWN, LEFT, RIGHT Fld TEol DE1IChr coll | 

CTRL_RKEY CTRL_W_KEY fono---- +------- te---=-- +Ent | 

CTRL_U_KEY CTRL.Z_KEY - | Lin OpL ISel ans | 

fon -~----- = --- $= - a ae 


TERRE eee ae ee ee ee | l 


123456789012 3456 78901234567890123456 7890123456 7890123456 789012345678901234567890 
ie evioiec bie 66 Rea Rice e oR ie Fie we wh ese & 00 7 BE OE 8 wali s Siw Clee wb Ole a PN wane We we ae 
| Hx++ 
Hx FUNCTIONAL DESCRIPTION: 
Hx This program produces a report of shipments for various 
Hx products broken down by division and department using an 
He input file with the shipment data for the past 4 quarters. 
f-< 





H 
FSHIPS IP F 41 DISK 
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If HELP is requested while the terminal page size is less than 17 lines, the 
following message will be displayed and the usual HELP action will not 
be performed: 


At least 17 lines on the screen are required by the editor to provide HELP 


HELP cannot be displayed unless there are enough lines on the screen to 
position the HELP window and still keep the ruler, prompt line, message 
line, and one line of the editing window visible. 
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If the keypad diagram is already displayed, you can get HELP information 
on any function (except GOLD) by using HELP_KEYPAD (default = PF2) 
and the key for which you want HELP information. HELP information 
will appear in the HELP window. The following example displays HELP 
for the CUT (default = KP6) and PASTE (default = PF1/KP6) functions: 


KP6 


The CUT function moves the selected range of lines to the paste buffer. The 
selected range of lines consists of the line identified by the SELECT 
function up to the current line. The line following the selected range of 
lines becomes the current line. The current column remains unchanged. 


The PASTE function inserts the contents of the paste buffer directly in 

front of the current line. The current line is moved down to accommodate 

the lines from the paste buffer. The current column and line remain 

unchanged. 

0 | 1 | 2 | 3 | 4 | 5 | 6 i 7 | 





123456 7890123456 7890123456 78901 234567890123456 7890123456 7890123456 78901234567890 
Line ELI R Tee ARE Re ee ea ere re 
oo He++ 
H* FUNCTIONAL DESCRIPTION: 
Hx This program produces a report of shipments for various 
Hx products broken down by division and department using an 
He input file with the shipment data for the past 4 quarters... 
R-— 


H 
FSHIPS IP F 41 DISK 
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2.5.3 HELP_SPECIFICATIONS Function 


The HELP_SPECIFICATIONS function (default = PF1/PF2) displays the 
specification format for the current line. In the following example, if 
the current line is line 100, the VAX RPG II editor displays the Control 
specification format when you use HELP_SPECIFICATIONS. 
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Currency symbol 
| Inverted print (DIJ) 

i oi Alternate collating sequence (SE) 

1 | | 1P forms position (1) 
| | | 

1 | | | 


7 | 





2 | 3 4 | 2) 6 
123456 7890123456789012345678901 23456 7890123456 7830123456789012345678901254567890 
Movs censne neha BecseMenccacivenens 


§ 100H*++ 
H* FUNCTIONAL DESCRIPTION: 
Hx This program produces a report of shipments for various 
Hx products broken down by division and department using an 
H* input file with the shipment data for the pate 4 quarters. 
H®-- 
H 
FSHIPS IP F 44 DISK 


oRecrcvvcccuseesenenececeessesanioe: 
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To restore the editing buffer to the entire screen, as shown in the following 
example, use the DISPLAY function (default = PF1/KP8). 





0 | Fl 3 4 | 5 | 6 ] 7 
123456 7890125456 7890125456789012345678901234567890123456 7890123456 7890123456 7890 
Go He++ — . 

H* FUNCTIONAL DESCRIPTION: 
H# This program produces a report of shipments for various 
Hx products broken down by division and department using an 
Hx input file with the shipment data for the past 4 quarters. 


H¥-- 
H ; 

FSHIPS IP F 4 DISK 

FSUMREP O F 98 LPRINTER 

E i QTY 4 20 

LSUMREP S5FL 500L 

ISHIPS AA 04 

ne | 1 S5DIV L2 
I 6 7 DEPT Li 
I 8 16 PROD 

I 17 24 QTY 

Cx 

Cc (Of XFOOTATY PROQTY 30 

c (Of PROQTY ADD DEPQTY  DEPQTY 30 


ZK-4335-85 
The VAX RPG II editor automatically updates the tab stops and the 


specification format, if displayed, for the specification type of the current 
line after a terminator (such as TAB) is typed. 
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2.5.4 FIND_NEXT Function 


The FIND_NEXT function (default = PF3) moves the cursor to the first 
character position of the next or last occurrence of the search string, de- 
pending on the current direction (ADVANCE or BACKUP). Use the FIND 
function to enter the search string. If the current direction is ADVANCE, 
the VAX RPG II editor will try to locate the next occurrence of the search 
string by searching forward from the current column and line to the end 
of the editing buffer. If the current direction is BACKUP, the VAX RPG II 
editor will try to locate the next occurrence of the search string by search- 
ing backward from the current column and line to the beginning of the 
editing buffer. If the VAX RPG II editor cannot locate the search string, 
the current column and line remain unchanged and an error message is 
displayed on the message line. See Section 2.8.2 for an example of the 
FIND_NEXT function. 


2.5.5 FIND Function 


The FIND function (default = PF1/PF3) locates the search string you 
specify. The VAX RPG II editor moves the cursor forward or backward to 
the beginning of the nearest occurrence of the search string, depending on 
the current direction (ADVANCE or BACKUP). If the current direction is 
ADVANCE, the VAX RPG II editor will try to locate the search string by 
searching forward from the current column and line toward the end of the 
editing buffer. If the current direction is BACKUP, the VAX RPG II editor 
will try to locate the search string by searching backward from the current 
column and line toward the beginning of the editing buffer. 


When you use the FIND function, the VAX RPG II editor displays the 
following prompt on the prompt line: 


Search for: 


You can enter up to 63 characters for the search string. If no search string 
is entered, the VAX RPG II editor will search for the last search string 
specified. Note that you cannot use control characters (RETURN, 

FORM FEED, TAB, and so on) in the search string. 


If the VAX RPG II editor cannot locate the search string, the current 
column and line remain unchanged and the following error message is 
displayed on the message line: 


String not found 
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Terminate the search string by pressing either the RETURN key or the 
ENTER key. 


See Section 2.8.2 for an example of the FIND function. 


2.5.6 DELETE_LINE Function 


The DELETE_LINE function places the current line in the deleted-line 
buffer, at the same time removing it from the screen. The line following 
the deleted line becomes the current line. The current column remains 
unchanged. If there is no line following the deleted line, the cursor is left 
in column 1 at the [EOB] mark. 


2.5.7 UNDELETE_LINE Function 


The UNDELETE _LINE function (default = PF1/PF4) inserts the contents 
of the deleted-line buffer before the current line. The new line becomes 
the current line, and the current column remains unchanged. 


If the deleted-line buffer is empty, no action is taken but an error message 
is displayed on the message line. 


2.5.8 PAGE Function 


The PAGE function (default = KP7) causes the editing buffer to move 
forward or backward to the next or preceding page, depending on the 
current direction (ADVANCE or BACKUP). A page is the start or finish of 
a section with the same specification type (column 6). 


In the following example, (1) the current cursor position is in column 34 
on line 120, (2) the current direction is ADVANCE, (3) the current setting 
for the SET STARTCOLUMN command is 7, and (4) when you use the 
PAGE function, the VAX RPG II editor will move the cursor to column 7 
on line 170. 
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0 | 1 | 2 | 3 | 4 | a) | 6 i 7 | 

TASER EARL ETA EE 
eX % % * % an HEE HH : 

{OH¥++ 

20H* FUNCTIONAL DESCRIPTION: 

SOH* This program produces a report of shipments for various 

40H* products broken down by division and department using an 

BOH* input file with the shipment data for the past 4 quarters. 





60H#-- 

70H 

BOFSHIPS IP F 41 DISK 

SOFSUMREP O F 98 LPRINTER 
100E QTY 4 20 


{40LSUMREP S5FL 500L 
420ISHIPS AA O1 


1301 1 5S DIV Le 
1401 6 7 DEPT Li 
1501 8 16 PROD 
1601 17 24 QTY 

170¢ 

480c Ol XFOOTOQTY PROQTY 30 

490C Ol PROQTY ADD DEPQTY DEPQTY 30 
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2.5.9 COMMAND Function 


The COMMAND function (default = PF1/KP7) allows you to execute 
a VAX RPG II editor command. The VAX RPG II editor displays the 
following prompt: 


Command: 
The following commands can be entered: 


¢ COMPILE 
e DEFINE KEY: 
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e =EXIT 


° HELP 

° INCLUDE 

° QUIT 

¢ RESEQUENCE 
e SET 

° SHOW 


e SUBSTITUTE 


Sections 2.6.1 through 2.6.10 describe these VAX RPG II editor commands 
and explain how to use them. 


2.5.10 SECTION Function 


The SECTION function (default = KP8) causes the editing buffer to move 
forward or backward the number of lines specified by the current setting 
of the SET SECTION command. The direction of the movement depends 
on the current direction (ADVANCE or BACKUP). The current column 
remains unchanged. See Section 2.6.8.6 for information on changing the 
SECTION value. See Sections 2.5.16 and 2.5.18 for information on setting 
the current direction. 


2.5.11 DISPLAY Function 


The DISPLAY function cee = PF1/KP8) removes any HELP informa- 
tion from the screen. 


2.5.12 REVIEW_ERROR Function 


If you use the VAX RPG II editor COMPILE command to compile your 
program, and your program contains errors, the VAX RPG II editor moves 
the cursor to the column and line where the first error occurs and displays 
the error text on the message line. The REVIEW_ERROR function 
(default = KP9) moves the cursor to the column and line where the next 
error occurs and displays the error message for that error on the message 
line. You can edit the line to correct the error and use the 
REVIEW_ERROR function again to move the cursor to the next error. 
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If you use REVIEW_ERROR and there are no more errors, the 
VAX RPG II editor displays the following message on the message line: 


No more errors found 


If you added or deleted a line in the program while correcting errors, 
when REVIEW_ERROR is used again the VAX RPG II editor will display 
the following message: 


Reissue the editor COMPILE command 


2.5.13 MOVE_TO_RULER Function 


The MOVE_TO_RULER function (default = PF1/KP9) places the cursor 
as close as possible to the top of the ruler (if the editing window is above 
it) or toward the bottom of the ruler (if the editing window is below it). 
The current column remains unchanged. Movement is restricted to the 
boundaries of the SET SCROLL offsets. If the ruler is positioned above 
the editing window and the last line of the buffer appears, movement is 
stopped. If the ruler is positioned below the editing window and the first. 
line of the buffer appears, movement is stopped. The MOVE__TO_RULER 
function will have no effect if no ruler is visible. 


2.5.14 DELETE_FIELD Function 


The DELETE—FIELD function (default = MINUS) places all the characters 
between the cursor and the next field (forward or backward, depending 
on the current direction) into the deleted-field buffer and replaces the 
characters with spaces. 


2.5.15 UNDELETE—FIELD Function 


The UNDELETE_FIELD function (default = PF1/MINUS) replaces the 
current field with the contents of the deleted-field buffer. If the contents 
of the deleted-field buffer are longer than the current field, the 

VAX RPG II editor copies to the current field until it is filled. If the 
contents of the deleted-field buffer are shorter than the current field, the 
VAX RPG II editor fills the current field to the right with spaces. Also, 
the cursor moves to the next field, depending on the current direction 
(ADVANCE or BACKUP). 


2-24 Using the VAX RPG II Editor 


2.5.16 ADVANCE Function 


The ADVANCE function (default = KP4) sets the current direction to 
forward, that is, to the right and down, toward the end of the editing 
buffer. ADVANCE sets the direction for the following functions: 

e¢ CHARACTER 

e DELETE—FIELD 

¢ UNDELETE_FIELD 


e FIELD 

e END_OF_LINE 
e FIND 

e FIND_NEXT 

e LINE 

e PAGE 

¢ SECTION 


2.5.17 BOTTOM Function 


The BOTTOM function (default = PF1/KP4) moves the cursor to the last 
line in the editing buffer. The current column remains unchanged. 


2.5.18 BACKUP Function 
The BACKUP function (default = KP5) sets the current direction to back- 


ward, that is, to the left and up, toward the beginning of the editing 
buffer. BACKUP sets the direction for the same functions as ADVANCE. 


2.5.19 TOP Function 


The TOP function (default = PF1/KP5) moves the cursor to the first line in 
the editing buffer. The current column remains unchanged. 
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2.5.20 CUT Function 


The CUT function (default = KP6) moves the selected range of lines to. 
the paste buffer. The selected range of lines consists of the line identified 
by the SELECT function (default = PERIOD) through the current line. 
The line following the selected range of lines becomes the current line. 
The current column remains unchanged. If there is no line following 
the selected range, the cursor is left in column 1 at the [EOB] mark. See 
Section 2.8.2 for an example using CUT. 


2.5.21 PASTE Function 


The PASTE function (default = PF1/KP6) inserts the contents of the paste 
buffer directly in front of the current line. The current line is moved down 
to accommodate the lines from the paste buffer. The current column and 
line remain unchanged. See Section 2.8.2 for an example using PASTE. 


2.5.22 SHIFT_LEFT Function 


The SHIFT_LEFT function (default = COMMA) deletes the character in 
the current column. All characters to the right of the current column are 
moved one column to the left, and the cursor position remains the same. 


In the following example if the cursor is in column 45 on line 350 and 
SHIFT_LEFT is used, the VAX RPG II editor deletes the blank in column 
45, moves all the characters to the right of the cursor one column to the 
left, and inserts a blank in column 80. 


Before using SHIFT_LEFT: 


eS ae Ce a 


1) i | Q | 3 4 

123456 7890123456 7890123456 7890123456 78901234567890123456789012345678901234567890 
H% RHEE € % ; ¥ HHX—-—-—-HRE 

3500 48 7Q1 G2 03 04 TOTAL’ 
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After using SHIFT_LEFT: 


| 4 | ? l 3 | rl l 5 6 | 7 
RULES ERE GS UYACISERE GYACISERE GCP CUBERS GLYACISERE GCVALUEERS Gl YACUEERE WLPACl) 
H% HRHRKE HH % RRX—-—— HK 


3500 48 901 02 Q3 04 TOTAL’ 





cursor 
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2.5.23 SHIFT_RIGHT Function 


The SHIFT_RIGHT function (default = PF1/COMMA) moves all characters 
in the current column through the end of the line one column to the right. 
A space is placed in the current column, and the cursor location remains 
unchanged. 


In the following example if the cursor is in column 44 on line 350 and 
SHIFT_RIGHT is used, the VAX RPG II editor moves all characters one 
column to the right of the cursor and inserts a blank in column 44. The 
blank in column 80 is lost. 


Before using SHIFT_RIGHT: 


Go ee We ere cit Caen thee tae PA oats a ge | 





1234567890123456 78901234567890123456 7890123456 78901234567890123456 7890123456 7890 
% HHRKH H % ¥% RRK———HE 


3500 46801 02 Q3 04 TOTAL’ 


cursor 
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After using SHIFT_RIGHT: 





) | 4 | 2 | 3 | 4 | 5 | 6 | 7 | 
123456789012345678901234567890123456 7890123456 7890123456 78901 234567890123456 7890 
RA HHKRE HH % HRK—-—— KK as 
3500 489'01 Q2 Q3 Q4 TOTAL’ 
cursor 
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2.5.24 FIELD Function 


The FIELD function (default = KP1) moves the cursor to the nearest . 
character in the next nonblank field. If the current direction is ADVANCE, 
using FIELD moves the cursor to the beginning of the next nonblank field 
following the current column. If the current direction is BACKUP, using 
FIELD moves the cursor to the end of the next nonblank field preceding 
the current column. 


In the following example if the cursor is in column 16 and the current 
direction is ADVANCE, using FIELD moves the cursor to column 21. 


1) | 1 | 2 | 3 | 4 l 5 | 6 | rs | 





123456 7890123456 7890123456 7890123456 7890123456 7890123456 789012345678901234567890 
RE % RR ¥--- #--- ¥--- p REHM MRK RE He RHR HR aan 


IINPUT Ag) 35 CA 


cursor after 
cursor before 
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In the following example if the cursor is in column 21 and the current 
direction is BACKUP, using FIELD moves the cursor to column 16. 


Sane Mee alg aoa Woo Rene fa ehe— ih ee elt Bose he pe oh 





123456 789012345678901234567890123456 7890123456 78901234567890123456 7890123456 7890 
HH % RRR ¥--- ¥--- | R-- RR —--¥—-—-—- HK ¥ 88K, 
TINPUT Ag B35 CA 


t 


cursor before 
cursor after 
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Note that you cannot use FIELD to move from one program line to 
another. 


2.5.25 END_OF_LINE Function 


The END_OF_LINE function (default = KP2) moves the cursor one 
column to the right of the end of the current line (the last nonblank 
character) if ADVANCE is the current direction. If the current direction is 
BACKUP, using END_OF_LINE moves the cursor one column to the right 
of the end of the preceding line. 


If the cursor is already at the end of the current line and the current 
direction is ADVANCE, using END_OF_LINE moves the current column 
one column to the right of the next line. 


In the following example if the cursor is in column 45 and the current 
direction is ADVANCE and if you use END_OF_LINE, the VAX RPG II 
editor moves the cursor to column 68. 


0.5 lt fle. ee SA SST RIGID GSR SES Ta AS 





£23456 7890125456 7890125456 7890123856 7890125456 7890123456 7890125456 7890125456780 
. a oe ee | ee onen 
3500 48 Qi a2 03 a4 TOTAL’ 
cursor before cursor after 
ZK-4343-85 
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In the following example if the cursor is in column 68 of line 350 and the 
current direction is BACKUP and if you use END_OF_LINE, the 
VAX RPG II editor moves the cursor to column 54 in line 340. __ 


0 | 4 | 2 I 3 4 | 5 I Ls) 7 
1234567890123456 7890123456 7890123456 7890123456 7890123456 7890123456 78901234567890 





RR HERKE H a: RRR HH sees 
3400 24 ‘PRODUCT’§ 
3500 48 01 Q2 03 Q4 TOTAL’§ 


cursor before 
cursor after 


2K-4344-85 


2.5.26 DELETE_TO_END_OF_LINE Function 


The DELETE_TO_END_OF_LINE function (default = PF1/KP2) deletes 
the characters from the current column to the end of the line. The cursor 
position remains unchanged. 


In the following example if the cursor is in column 46 and you use 
DELETE_TO_END_OF_LINE, the VAX RPG II editor deletes the charac- 
ters in columns 46 through 67. 


Before using DELETE_TO_END_OF_LINE: 


a a ee ee ee ee ee 


) 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 
HE RRRHH H ¥ % HER—-—-—RE core 

3500 48 ‘Qi @2 Q3 04 TOTAL’ 


t 


cursor 
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After using DELETE_TO_END_OEF_LINE: 


0 | i | 2 | 3 | 4 | a) | Ls) | 7 
123456 7890123456 789012345678901234567890123456 7890123456 7890123456 78901234567890 
H¥ HRRXKK * ¥% REK—-——- HE Serecar 


3500 48 '§ 





cursor 
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2.5.27 CHARACTER Function 


The CHARACTER function (default = KP3) moves the cursor position 
to the right or left, depending on the current direction (ADVANCE or 
BACKUP). If you attempt to move the cursor to the right of column 81 
or to the left of column 1, no action is taken and an error message is 
displayed on the message line. . 


In the following example, if the cursor is in column 47 and the current 
direction is ADVANCE and if you use CHARACTER, the VAX RPG II 
editor moves the cursor to column 48. If the cursor is in column 47 and 
the current direction is BACKUP and if you use CHARACTER, the 

VAX RPG II editor moves the cursor to column 46. 


Th 2: ear ubrs By at eee ee ee ee ee 


0 | 
123456 7890123456 7890123456 78901234567890123456 7890123456 7890123456 78901234567890 
xX RHEKHEK % ¥ ¥ RER—--— HK 
3500 49 H@M a2 a3 a4 TOTAL’ 





tt after (ADVANCE) 
cursor before 
cursor after (BACKUP) 
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2.5.28 COLUMN Function 


The COLUMN function (default = PF1/KP3) highlights the number of the 
current column by causing the column number in the 80-column ruler to 
blink. The column function takes no action if no ruler is visible. 


On a terminal without Advanced Video Option (AVO), the COLUMN 
function performs no action. 


On the VK100 (GIGI) terminal, the blinking for the COLUMN function is 
sometimes wider than the width of one character. 


2.5.29 ENTER Function 


The ENTER function (default = ENTER) terminates the FIND function (see 
Section 2.5.5) and VAX RPG II editor commands (see Section 2.5.9). — 


The ENTER function also clears any information on the message line. 


2.5.30 LINE Function 


The LINE function (default = KPO) causes the cursor to move one line up 
or down, depending on the current direction (ADVANCE or BACKUP). 
The cursor is moved to the current setting for the SET STARTCOLUMN 
command. 


2.5.31 OPEN_LINE Function 


The OPEN_LINE function (default = PF1/KP0) creates a new line above 
the current line. The new line becomes the current line, and the cursor is 
moved to the current setting for the SET STARTCOLUMN command. If 
the current setting for the SET STARTCOLUMN command is greater 
than 6, the new line will have the same specification format as the 
previous line. See Section 2.8.2 for an example of the OPEN_LINE 
function. 
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2.5.32 SELECT Function 


The SELECT function (default = PERIOD) marks the current line as the 
beginning of the range of lines you are selecting (select range). The 
SELECT function highlights column 1 of the current line in reverse video. 
You can use SELECT to select a range of lines to be deleted or moved. 
You can then use CUT to move the selected lines from the editing buffer 
to the paste buffer (see Section 2.5.20), and you can use PASTE to reinsert 
them into the editing buffer at another location (see Section 2.5.21). The 
cursor position in the line does not matter—the entire line will be moved 
into the paste buffer when CUT is used. | 


If you select a line as the beginning of a select range and then delete that 
line, the select range will no longer be in effect and a message will be 
displayed on the message line. 


You cannot select the line where [EOB] appears. If you select a range of 
lines that includes [EOB], [EOB] will not be placed in the paste buffer. 


See Section 2.8.2 for an example of the SELECT function. 


2.5.33 RESET Function 


You can clear the current setting for the SELECT function by using the 
RESET function (default = PF1/PERIOD). 


2.5.34 UP Function 


The UP function (default = UP) causes the cursor to move up one line. 
The current column remains unchanged. If the current line is the first line 
in the editing buffer, the cursor will not be moved and an error message 
will be displayed. 


2.5.35 DOWN Function 
The DOWN function (default = DOWN) causes the cursor to move down 
one line. The current column remains unchanged. If the current line is the 


last line in the editing buffer, the cursor will not be moved and an error 
message will be displayed. 
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2.5.36 


2.5.37 


2.5.38 


2.5.39 


2.5.40 


RIGHT Function 


The RIGHT function (default = RIGHT) moves the cursor to the right one 
column. If the current column is 80, the cursor is not moved and column 
81 becomes the current column. If the current column is 81, the cursor 
will not be moved and an error message will be displayed. 


LEFT Function 


The LEFT function (default = LEFT) moves the cursor to the left one 
column. If the current column is column 1, the cursor will not be moved 
and an error message will be displayed. 


FIELD_ BACKWARD Function 


The FIELD_BACKWARD function (default = BS_KEY) moves the cursor to 
the tab stop preceding the current column. Or, if the cursor is before the 
first tab stop, it moves the cursor to column 1. If the current column is 1, 
the cursor will not be moved and an error message will be displayed. 


DELETE_CHARACTER Function 


The DELETE_-CHARACTER function (default = DEL_KEY) replaces the 
character to the left of the cursor with a space and moves the cursor one 
column to the left. If you try to delete a character to the left of column 1, 
the cursor will not be moved and an error message will be displayed. 


NEW_LINE Function 


The NEW_LINE function (default = RET_KEY) creates a new line © 
following the current line. The lines following the current line are moved 
down to accommodate the new line. If the current line is the last line in 
the current buffer, a new last line is created. The cursor is moved to the 
current setting for the SET STARTCOLUMN command. If the current 
setting for the SET STARTCOLUMN command is greater than 6, the new 
line will have the same specification format as the previous line. 
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2.5.41 


2.5.42 


2.5.43 


2.5.44 


FIELD__FORWARD Function 


The FIELD_FORWARD function (default = TAB_KEY) moves the cursor 
to the next tab stop after the current column. If the cursor has already 
passed the last tab stop, FIELD. FORWARD moves the cursor to 

column 81. If the current column is column 81, the cursor will not be 
moved and an error message will be displayed. 


REFRESH_SCREEN Function 


The REFRESH_SCREEN function (default = CTRL_R_KEY and 
CTRL_—W_KEY) rewrites the screen display. The cursor location remains 
unchanged. 


DELETE_TO_BEGINNING_OF_LINE Function 


The DELETE_TO_BEGINNING_OF_LINE function 
(default = CTRL_U_KEY) replaces the characters from the current column 
to column 1 with spaces. The cursor location remains unchanged. 


EXIT Function 


The EXIT function (default = CTRL__Z_KEY) writes the editing buffer to 
an output file as described in Section 2.1.4. If a journal file was created, it 
is not saved. 


If you have issued the VAX RPG II editor COMPILE command, and then 
leave the VAX RPG II editor using EXIT, the following message will be 
displayed: 


Subprocess terminated 


If you invoked the VAX RPG II editor with the /NOOUTPUT qualifier or 
the /READ_ONLY qualifier, the following message will be displayed: 


Use EXIT with an output file specification or QUIT 


The EXIT function performs the same function as the EXIT/NOSAVE 
command. 
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2.6 Editor Commands 


This section describes the VAX RPG II editor commands and explains how 
to use them. You must issue the COMMAND function before executing 

a VAX RPG II editor command. Section 2.5.9 discusses the COMMAND 
function. 


The following conditions exist when executing VAX RPG II editor 
commands: 


e If you type a command with a missing required parameter, you will 
receive a prompt to supply the missing parameter. 


¢ Qualifiers can appear anywhere on the line; they do not have to 
immediately follow the command and can appear in any order. 


¢ Qualifiers can be negated. 
e Command line input can be in uppercase, lowercase, or both. 


e Abbreviations are allowed. You must type enough information to 
resolve any ambiguity. 


e You can enter full line comments, end-of-line comments, and blank 
lines in a command line. 


e You can continue a command line by entering a hyphen (-) at the end 
of the line. You will get a prompt for more input. 


e Terminate a command by pressing either the RETURN key or the 
ENTER key. 


2.6.1 COMPILE Command 


The COMPILE command compiles the source code in the editing buffer 
and displays the following messages: 


Subprocess activated 
Beginning compilation 


The message “Subprocess activated” appears only when the COMPILE 
command is issued for the first time during an editing session. 


The format of the COMPILE command is as follows: 


COMPILE [/LIST] 
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The following message is displayed to indicate how many errors were 
found: 


Compilation complete - n errors found 


If n is 0, no errors were found and you can leave the VAX RPG II editor, 
then link and run your program. 


If the compilation encounters errors, the error text associated with the 
first error is displayed on the message line and the cursor is moved to the 
column and line where the first error occurs. If there is more than one 
error, use the REVIEW_ERROR function to move the cursor to the column 
and line causing the next error. See Section 2.5.12 for more information 
on the REVIEW_ERROR function. 


You can use only the /LIST qualifier with the COMPILE command to 
create a listing file for the compiled source code. The default is /NOLIST. 
The /OBJECT qualifier is always in effect. However, if the compilation 
encounters fatal errors, an object module will not be produced. 


You can specify a symbol definition at the DCL command level to change 
the defaults for a compilation. When you issue the VAX RPG II editor 
COMPILE command, the compiler will use these settings. In the following 
example, the symbol RPG is defined to compile a program and generate a 
listing file with machine-generated code. The compiler will also generate 
code in the program to check for blanks in numerics. 


$ RPG :== RPG/LIST/MAC/CHECK : BLANKS_IN_NUMERICS 


You must use COMPILE/LIST in the VAX RPG II editor to get a program 
listing. 


To use the debugger after you enter the COMPILE command, you must 
first define the following command before invoking the VAX RPG II editor: 


$ RPG := RPG/DEBUG 


See Chapter 5 for information on how to set the appropriate source file for 
debugging. 

The COMPILE command requires each line in the editing buffer to be 140 
characters or less. 


If you define RPG to invoke something other than the VAX RPG II 
compiler, or if the VAX RPG II compiler encounters an unexpected error, 
the following message is displayed on the message line: 


Unexpected error during compilation - leave editor and try DCL RPG command 
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2.6.2 DEFINE KEY Command 


The DEFINE KEY command allows you to bind specific keys to specific 
VAX RPG II editor functions. These functions are listed with their default 
key definitions in Table 2-2 at the beginning of Section 2.5. 


- You can bind the following keys in the VAX RPG II editor: 


¢ Control keys 

e Cursor keys 

e Editing keys (LK201 except Rainbow) 
¢ Function keys (LK201 except Rainbow) 
e Keypad keys 

¢ Gold versions of all these keys 


Exceptions: 


The following list contains seven control key restrictions. These are special 
functions of the VAX/VMS operating system. 


e CTRL_C_KEY 
e CTRL—O_KEY 
e CTRL_—T_KEY 
e CTRL_Q_KEY 
e CTRL_X_KEY 
e CTRL_S_KEY 
e CTRL_Y_KEY 


Note that key redefinition does not cause automatic update to the 
VAX RPG II editor keypad diagram and key-specific HELP text. 


The format of the DEFINE KEY command is as follows: 
DEFINE KEY[/GOLD] key_name function 


In this command, -/GOLD indicates that you must press the GOLD key 
followed by key_name to execute the chosen function. For example: 


DEFINE KEY/GOLD KP& CUT 


When you enter this command and then press the GOLD key, followed 
by pressing the KP5 key, the CUT function is executed. 
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If key_name is not a valid definable key, or if function is not a valid 
VAX RPG II editor function that you can bind to a key, an error message 
is displayed. 


To redefine the GOLD key, enter the following line at the command 
prompt: . 


DEFINE KEY key_name GOLD 


To remove the GOLD key completely, enter the following line at the . 
command prompt: 


DEFINE KEY/GOLD PF1 GOLD 


Note that if you use a key name other than PF1 with this command, it 
will be treated as if PF1 had been entered. 


Note also that you must redefine the GOLD key (default = PF1) before 
you can define the PF1 key to a function other than GOLD. 


See Table 2-2 for a list of default key definitions. This table provides a list 
of definitions that you can bind to keys. Note that in some cases, more 
than one key is bound to the same procedure. Note also that TAB_KEY 
and CTRL_I_KEY (the default settings for FIELD_FORWARD), and the 
RETURN_KEY and CTRL_M_KEY (default settings for RETURN), can 
only be bound to the same function, while the F10 key and 

CTRL _—Z_KEY (the default settings for EXIT) may be bound to separate 
functions. 


The SECTION—_FORWARD and the SECTION_BACKWARD functions are 
not bound by default to any key on the VT100 and VK100 (GIGI) terminal 
keyboards. However, you can bind any of the valid definable keys to 
those functions. 


Table 2-3 contains additional keys that you can bind to the functions 
listed in Table 2-2. 


Table 2-3: VAX RPG Il Keynames for Valid Definable Keys 
VT100 Family 


VAX RPG II Keyname__. LK201 VK100 (GIGD 
PF1 PFi] PFI 

PF2 | 

PF3 


PF4 PF4 
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Table 2-3 (Cont.): 


VAX RPG II Keyname 
KPO,KP1 ... KP9 
PERIOD 
COMMA 
MINUS 
ENTER 
UP 
DOWN 
LEFT 
RIGHT 
E1 
E2 
E3 
E4 
E5 
E6 
HELP 
DO 
F7... F20 
TAB_KEY 
RET_KEY 
DEL_KEY 
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VAX RPG II Keynames for Valid Definable 


Keys | _ 
| ; VT100 Family 
LK201 VK100 (GIGI) 

01...9 01...9 
L] L) 

L) Al 

Bl ei 
[ENTER] [ENTER] 
T 1 

| { 

= ym 

a = 
[FIND] /E1 

/E2 

[REMOVE] /E3 

[SELECT] /E4 

[PREV SCREEN] /E5 

/E6 

/F15 

/F16 

F7... F20 

<X] 


Table 2—3 (Cont.): VAX RPG II Keynames for Valid Definable 


Keys 
VT100 Family 
VAX RPG II Keyname LK201 VK100 (GIGI) 
LE_KEY Line-feed 
BS_KEY 
CTRL_A_KEY | 
CTRL _—Z_KEY 


Note the list of exceptions at the beginning of this section. 


You can modify the key bindings shown in Table 2-2 at VAX RPG II 
editor start-up by creating a start-up command file with the desired 
DEFINE KEY commands. For more information on using DEFINE KEY, 
see Section 2.7.2. 


2.6.3 EXIT Command 


The EXIT command writes the editing buffer to the output file, leaves 
the VAX RPG II editor, and returns to the DCL command prompt ($), as 
shown in the following example. 
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eS FOB P2012 3400 (0201 5856701012 Ss Be 1830 te 38507070 1c 520672820 Veet G 13 20 te eo (eat 
; " #% i 3 it Se Vo en | otete feet | i 2 2 ee Se 
10H#++ . 
20H* FUNCTIONAL DESCRIPTION: 
SOH® This program produces a report of shipments for various 
40H products broken down by division and department using an 
5OH* input file with the shipment data for the past 4 quarters. 


60H#-- 

70H ; 

BOFSHIPS IP F 41 DISK 

SOFSUMREP O F 98 LPRINTER 
100E . QTy 4 20 


410LSUMREP 55FL 500L 
420ISHIPS AA O14 


1301 1 S5DIV L2 
1401 6 7 DEPT Li 
1501 8 16 PROD 
1601 17 24 QTY 
170C% 

180C 04 XFOOTATY PROGTY 30 

190C 04 PROQTY ADD DEPQTY DEPATY 30 





53 records written to file MYDISK: [MYDIRECTORYIMYFILE. RPG; 2 
$i 
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The format of the EXIT command is as follows: 
EXIT [/SAVE] [file-spec] 
The output file is one of the following: 


° The file name you supplied with the EXIT command 


¢ The file name you supplied with the /OUTPUT qualifier to the 
RPG/EDIT command . 


¢ The same file name as the input file you specified when you invoked 
the VAX RPG II editor, if both the /READ_ONLY and /NOOUTPUT 
qualifiers were not used with the RPG/EDIT command 


The VAX RPG II editor will write the editing buffer to the output file even 
if no changes have been made. 
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You can use the /SAVE qualifier with the EXIT command to save the 
journal file, if one was created. The file name of the journal file is the 
name of the output file, if specified, with the JOU file type. If a journal file 
name was not specified, the VAX RPG II editor uses the same file name as 
the input file. See Section 2.1.3 for information on journal files. | 


If an error occurs during the execution of an EXIT/SAVE command and 
you resume editing, the journal facility will still be in effect. 


If you have issued the VAX RPG II editor COMPILE command and then 
leave the VAX RPG II editor by typing the EXIT command, the following 
message will be displayed on the message line: 


Subprocess terminated 


2.6.4 HELP Command 


The HELP command displays information on VAX RPG II editor functions 
and commands in the HELP window of the VAX RPG II editor screen. 
The following example shows what the screen looks like after you issue 
the COMMAND function, type the HELP command, and press either the 
RETURN key or the ENTER key. 
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This help information describes the VAX RPG II editor. Information is 
included on editing functions performed by pressing keypad keys and control 
keys. Editor commands issued with the COMMAND function are described. 
Brief notes describing the journaling facility are included. You can read 
this help information while using the editor by typing the HELP command or 
using the help functions. 


Additional information available: 


Commands Cursor Functions Help Journal Keypad 
Specifications 






0 | 1 I 2 | 3 I 4 | 

123456 7890123456 7890123456 7890123456 7890123456 7890123456 7890123456 7890 

LCP EEE REEL TR RR eR RR ee a ee ee 
HX++ 

H* FUNCTIONAL DESCRIPTION: 

H* This program produces a report of shipments for various 

Hx products broken down by division and department using an 

Hk input file with the shipment data for the past 4 quarters. 
H*-- 


H 
FSHIPS IP F 44 DISK 
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The format of the HELP command is as follows: 
HELP [/FULL] [/PAGE] [/PROMPT] list-of-topics 


The /PAGE qualifier is similar to the DCL HELP command /PAGE 
qualifier. If the HELP text does not fit in a logical page (in this case, 
the HELP window), the text is displayed one page at a time and you 
must press the RETURN key to advance to the next page. The default is 
/NOPAGE. 
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The /PROMPT qualifier is similar to the DCL HELP command /PROMPT 
qualifier. After HELP for the given list of topics is displayed, you are 
prompted for additional topics, which are then linked to the current list of 
topics. Press the RETURN key repeatedly to back up through the levels of 
HELP text. Press CTRL/Z to terminate the HELP command. The default 
is /NOPROMPT. 


The /FULL qualifier uses the entire screen, except for the prompt and 
message lines, to. display HELP text. When the requested HELP text has 
been displayed, the previous screen layout is restored. You are prompted 
to press the RETURN key before the screen is repainted. If the previous 
screen contained HELP text, it is not restored. Instead, the last 11 lines of 
text from the current HELP command is left in the HELP window. The 
default is /NOFULL. 


Note that /FULL, /PAGE, and /PROMPT are positional qualifiers. If they 
occur after a topic or subtopic, they are interpreted as subtopics on which 
HELP is desired. 


There is no fixed number on the list of topics. Whatever can fit on the 
command line is valid. If you use the /PROMPT qualifier, you can extend 
the depth indefinitely. 


By default, the VAX RPG II editor searches its own HELP library 
(SYS$HELP:RPGEDIHLP) for the given list of topics. 


You can access other libraries in the following ways: 
e If the first topic has the form @filespec, that library is searched 
instead. 


e If you define logical names of the form HLP$LIBRARY, 
HLP$LIBRARY_1 .. . HLP$LIBRARY_999, the LIBRARIAN searches 
them in the following order: root library, main library, process li- 
braries, group libraries, and system libraries. 
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The following example shows what the screen looks like after you issue 
the COMMAND function, type HELP COMMANDS, and press either the 
RETURN key or the ENTER key: 






COMMANDS 


Editor commands are executed by pressing the COMMAND function (PFI/KP7 - see 
information for FUNCTIONS). Any command, parameter or qualifier can be 
abbreviated so that the information typed is unambiguous. The prompt 
"Command: " is displayed in reverse video on the prompt line. Any 

ener Sota that can normally be typed in the editor may be typed at the 
promp 


Qualifiers can be negated and can also appear in any order on a command line 
after the name of the command, 


Blank command lines are ignored. Also any text on a command line after an 
exclamation point ("!") is ignored. 


Additional information available: 





COMPILE DEFINE’ EXIT HELP INCLUDE QUIT 
RESEQUENCE SET SHOW SUBSTITUTE . 
0 | 1 | 2 | 3 | 4 | 5 | 6 } 7? | 
123456 7890123456 7890123456 7890123456789012345678901 23456 789012345678901234567890 
Main Gk ote aco ae Rea icaw Mave eaib alse Wiece eine Mace Gg aonb @ ecaue Gin ainislale sue eels ee acese bere 
H¥++ 


H* FUNCTIONAL DESCRIPTION: 

Hx This program produces a report of shipments for various 
H% products broken down by division and department using an 
H¥ input file with the shipment data for the past 4 quarters. 
Hk-- : 





H 
FSHIPS IP F 41 DISK 
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After you press either the RETURN key or the ENTER key to execute 

a HELP command and HELP information is displayed, the VAX RPG II 
editor returns the cursor to its current column and line so you can resume 
editing. 


If you terminate the HELP display by pressing CTRL/C, you must type a 
terminator to resume editing. 
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2.6.5 INCLUDE Command 


The INCLUDE command copies a text file into the source buffer using the 
VAX RPG II editor. The format of the INCLUDE command is as follows: 


INCLUDE file-spec 


The file is copied into the editing buffer, immediately before the current 
line. The cursor position remains unchanged. Note that the lines read in 
are not syntax checked. 


If the INCLUDE command is successful, the number of records read in is 
displayed on the message line. 


2.6.6 QUIT Command 
The QUIT command allows you to leave the VAX RPG II editor and 


return to the DCL command level, without writing the editing buffer to 
the output file, as shown in the following example. 
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1) | 1 | 2 | 3 4 | 5 | 5) | ¢ | 
ses £50 O20 Bed 006 Fa O12 ene Zou e546 70 Ute oab 10 01g tebe 7c lea tie/u 1012 sib 727) 
FT rn ee ee Tre ee eH HH 
10H#++ 
20H* FUNCTIONAL DESCRIPTION: . 
SOH* This program produces a report of shipments for various © 
40H* products broken down by division and department using an 
5OH* input file with the shipment data for the past 4 quarters. 








60H*-- 

70H 

BOFSHIPS IP F 41 DISK 
SOFSUMREP O F 98 LPRINTER 
100E QTY 4 20 


410LSUMREP 5SS5FL S500L 
{20ISHIPS AA O41 


1301 1 SDIV L2 
1401 6 7 DEPT Li 
1501 8 16 PROD 
1601 17 24 QTY 
170C# | 7 

180C 04 XFOOTATY PROQTY 30 

190C 04 PROQTY ADD DEPQTY  DEPATY 30 


Command: QUIT 


‘fi 
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The format of the QUIT command is as follows: 


QUIT [/SAVE] 


_ Use the QUIT command if you have made no changes to the editing 
buffer or if you have decided not to save the changes you made. If you 
have made changes, or if you have pressed keys to move the cursor past 
the last nonblank character in any line, the VAX RPG II editor displays the 
following message: 


Buffer modifications will not be saved, continue quitting (Y or N)? 
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You can respond by typing Y, YE, or YES. Any other response will 
continue the editing session. If you resume editing, a journal file for your 
edits will not be created. To resume journaling, you must leave the 

VAX RPG II editor, and invoke the VAX RPG II editor again. 


You can use the /SAVE qualifier with the QUIT command to save the 
journal file, if one was created. 


If you issue the VAX RPG II editor COMPILE command and then leave 
the VAX RPG II editor by typing the QUIT command, the following 
message will be displayed on the message line: 


Subprocess terminated 


2.6.7 RESEQUENCE Command 


The RESEQUENCE command either generates a new line number for each 
program line in the editing buffer or resequences existing line numbers. 
The format of the RESEQUENCE command is as follows: 


RESEQUENCE [/REMOVE] [initial-value [increment] ] 


The RESEQUENCE command renumbers program lines up to the first line 
containing a double slash (//) and a blank or a double asterisk (**) and a 
blank in columns 1 through 3. Lines are numbered beginning at the initial 
value (default = 10) and are incremented by the increment value 

(default = 10). 


The maximum line number is 99,999. If during resequencing, a line 
number plus the increment exceeds 99,999, that line and all remaining 
lines are numbered 99,999. In this case, reissue the RESEQUENCE 
command with smaller values for the initial value and increment by the 
increment value. 


The RESEQUENCE/REMOVE command will remove all line numbers in 
the editing buffer. 


The following command renumbers the line numbers in the editing buffer 
beginning with 100 and increments each number by 20: 


RESEQUENCE 100 20 


See Section 2.8.2 for another example of the RESEQUENCE command. 
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2.6.8 SET Command 


The VAX RPG II editor has eight optional functions which are controlled 
by the SET command: 


° COMMAND 
° DEFAULT 

° HELP 

° RULER 

° SCROLL 

° SECTION 


¢ STARTCOLUMN 
¢ SYNTAXCHECK 


The SET command controls VAX RPG II editor options. Once set, these 
options are in effect until you leave the VAX RPG II editor or reissue the 
SET command. 


You can include SET commands in a start-up command file. See 
Section 2.7.2 for information on start-up command files. 


The format of the SET command is as follows: 


SET option 


2.6.8.1 COMMAND Option 


The COMMAND option allows you to process additional start-up com- 
mand files at the beginning of the VAX RPG II editing session. The format 
of the COMMAND option is as follows: 


SET COMMAND file-spec 


For information on the SET COMMAND option, see Section 2.7.2. 
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2.6.8.2 DEFAULT Option 


The DEFAULT option allows you to determine the default value of 
qualifiers used in other editor commands. The format of the DEFAULT 
option is as follows: 


SET DEFAULT option 


For example, the following command means that any later HELP com- 
mand uses the PAGE and PROMPT options by default. You can turn 
defaults off by using the negated form of an option. (For example, SET 
DEFAULT NOPROMPT.) 


SET DEFAULT PAGE, PROMPT 


2.6.8.3 HELP Option 


The HELP option allows you to choose a variety of settings. The format 
of the HELP option is as follows: 


SET HELP { KEYPAD | NONE | SPECIFICATIONS } 


The HELP KEYPAD option has the same effect as using the 
HELP_KEYPAD function (default = PF2). See Section 2.5.2 for information 
on HELP_KEYPAD. 


The HELP NONE option allows you to start up a as if you used the 
DISPLAY function. See Section 2.5.11 for information on the DISPLAY 
function. 


The HELP SPECIFICATIONS option has the same effect as using the 
HELP_SPECIFICATIONS function (default = PF1/PF2). See Section 2.5.3 
for information on HELP_SPECIFICATIONS. 


2.6.8.4 RULER Option 


The RULER option moves the three-line 80-column ruler with tab stops as 
a unit, to either the top or bottom of the current window. The 
SET RULER NONE option removes the ruler from the screen. 


The format of the RULER option is as follows: 


SET RULER { TOP | BOTTOM | NONE } 
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The following example shows an editor screen as it appears after a 
SET RULER BOTTOM command, with an 18-line terminal page size. The 
next example shows the same screen followed by a HELP request. 


FSHIPS IP F 41 DISK 
FSUMREP O F 98 LPRINTER 
E QTY 4290 


LSUMREP S5FL 500L 
ISHIPS AA O14 
I 


4 5 DIV Le 
i I 6 7 DEPT Li 
I 8 16 PROD 
I 17 24 QTY 
Cx 
Cc «(Ot _XFOOTQTY PROQTY 30 
Cc Of PROQTY ADD DEPQTY DEPQTY 30 


3 | 4 | 5 | 





H HEE R--- #--- #--- a k¥—-—-—¥-—- HE RR HR HH 
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PFi/PF2 ~ RPG II specification formats Peaceeane ton seeee iesaase= aneaerata 


Press the PFi/KP7 key and type HELP for | Gold ! Help Hiss Fnd DIL UdLt 
information on commands and functions. a lorena Sr a eae are ea a pa + 
For help on a specific key, press the IPag cna See DeplRev MovIDIF UdF | 
PF2 key followed by the key for which Peonaes Peres santas ase Peneaane + 
you want help information. Ady Bot Bok Topicut deus ShRI 
Other keys: BS_KEY DEL_KEY RR aA: Ea oe, cee ohare tne an ae + 
TAB_EEY UP, DOWN, LEFT,RIGHT IF lid Io! DEIIchr Call | 
CTRL_R_FEY CTRL_W_KEY +------- $------- +------- +Ent | 
CTRL_U_KEY CTRL_Z_KEY | Lin OpL 1Sel Res! I 
$o-------------- +------- +------- + 
ff I 6 7 DEPT Li 
I 8 16 PROD ; . 
) | 5 | | 





i | 2 | 3 | 4 
12345678901234567830123456789012345678901234567890123456 7890123456 78901234567 


Lhd 


% KKK ¥--- #--- #--- 2 RR K-——RE RE HER wees 





2K-4353-85 


2.6.8.5 SCROLL Option 


The SCROLL option specifies the region within the editing window where 
the cursor will stay. 


The format of the SCROLL option is as follows: 


SET SCROLL [top-offset [bottom-offset]] 
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Top-offset is the number of lines from the top of the editing window to 
the top of the scrolling region. Bottom-offset is the number of lines from 
the bottom of the scrolling region to the bottom of the editing window. If 
bottom-offset is omitted, the current offset from the bottom is not changed. 
If the top and bottom offsets are omitted, both offsets are set to the initial 
editor defaults of zero. 


If you enter SET SCROLL 0 1, then the cursor will move from the line 
next to the ruler on the top, to within one line above the bottom of the 
editing window. If you want to keep the cursor from hitting the top line, 
enter a number greater than zero for top-offset. The higher the number, 
the greater the number of source code lines that will remain on the screen 
between the cursor and the top or bottom of the editing window. 


2.6.8.6 SECTION Option 


The SECTION option specifies the number of lines the VAX RPG II editor 
will move the cursor (forward or backward) when the SECTION function 
(default = KP8) is used and there is no HELP information displayed. You 
can specify any value between 1 and 5 less than the terminal page length. 
By default, the bottom line of the editing window moves to the top (just 
under the tab stops), regardless of the size of the window. 


The format of the SECTION option is as follows: 
SET SECTION lines 


If you specify a SECTION value other than the default (when the HELP 
window is displayed), the SECTION value is proportional to the visible 
number of lines in the editing window. 


2.6.8.7 STARTCOLUMN Option 
The STARTCOLUMN option specifies the current column for the following 


functions: 

e NEW_LINE 

e OPEN LINE 
e LINE 

e PAGE 


The format of the STARTCOLUMN option is as follows: 


SET STARTCOLUMN column 
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The default value is column 7. When the setting for the STARTCOLUMN 
option is greater than 6, the RETURN key and OPEN_LINE 

(default = PF1/KPO) function supply a specification type in column 6 that 
is the same as is present on the current line. 


2.6.8.8 SYNTAXCHECK Option 


The SYNTAXCHECK option specifies that syntax checking and automatic 
right justification of numeric fields will occur. 


The format of the SYNTAXCHECK option is as follows: 
SET SYNTAXCHECK { ON | OFF | PROMPT } 


By default, the VAX RPG II editor starts up with the SYNTAXCHECK 
option set on. This setting can be changed in a start-up command file, or 
interactively. 


If you modify a line when syntax checking is on, and then attempt to 
move off the line, one of the following events will occur: 


e If there are no errors on the line and all numeric entries are properly 
justified, the requested action takes place. 


e If there are no errors on the line, but one or more numeric entries are 
not properly justified, the numeric entries are justified, the justified 
fields are highlighted, and the requested action takes place. The 
highlighting is removed from the fields when the next line is syntax 
checked. 


e If a syntax error is detected, the requested action does not take place. 
The cursor is positioned at the column of the error, and the error 
message is displayed on the message line. You can either correct the 
error or ignore the error by immediately moving off the line. Another 
syntax check will take place on that line only if you modify it again. 


If you enter table and array data while SYNTAXCHECK is set on, there is 
a risk that the data will be right-justified as if it were part of the source 
program. This will yield unexpected results. Therefore, it is recommended 
that SYNTAXCHECK be set off while entering table and array data, or 
that you use the PROMPT argument with SYNTAXCHECK. When the 
PROMPT argument is in effect, the VAX RPG II editor will highlight any 
proposed numeric right justification before it occurs and will prompt you 
to confirm whether you want right justification. 
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Note that SYNTAXCHECK detects all errors, regardless of the severity. 
Therefore, depending on the qualifiers you use when compiling, it is 
possible that informational messages that you see in the editing session 
will not be issued by the compiler. You can ensure that the errors will 
be reported by compiling at DCL with the /WARNINGS=ALL qualifier. 
This will cause both warning and informational messages to be sent. See 
Section 3.1.2.8 for additional information on this qualifier. 


2.6.9 SHOW Command 


The SHOW command displays the current settings for the following 


options: 

e DEFAULT 
e SCROLL 

e SECTION 


° STARTCOLUMN 
e SYNTAXCHECK 
e VERSION 


The format of the SHOW command is as follows: 
SHOW option 


The current settings appear on the message line, as shown in the following 
examples: 


COMMAND: SHOW DEFAULT PAGE,PROMPT 
Current defaults are NOPAGE,NOPROMPT 


Command: SHOW SCROLL 
Scroll offset from top is 0, from bottom is 0 


Command: SHOW SECTION 
Section length is: 18 or when HELP is displayed: 7 


Command: SHOW STARTCOLUMN 
STARTCOLUMN value is: 7 


Command: SHOW SYNTAXCHECK 
SYNTAXCHECK is ON 
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The VERSION argument displays the current version of the VAX RPG II 
editor and a VAX RPG II copyright statement, as shown in the following 
example: 


Command: SHOW VERSION 
VAX RPG II V2.1 editor COPYRIGHT (C) DIGITAL EQUIPMENT CORPORATION 1986 


2.6.10 SUBSTITUTE Command 


The SUBSTITUTE command allows you to substitute text using the 
VAX RPG II editor. The format of the SUBSTITUTE command is as 
follows: 


SUBSTITUTE search-argument replace-argument [/SELECT] [/QUERY] 


The SUBSTITUTE command replaces all occurrences of the search- 
argument with the replace-argument in the specified range. If the 
/SELECT qualifier is specified, the command applies to all lines in the 
select range. Otherwise, it applies to all lines in the buffer. 


Only exact matches of the search-argument with text in the editing buffer 
are performed. 


Only equal length substitutions are performed. If one argument is shorter 
than the other, it is padded on the right with spaces before searching and 
replacing begins. 


If you specify the /QUERY qualifier, then at each occurrence of the string 
to be substituted the following occurs: 
e The string to be substituted is highlighted. 


e A “Substitute this occurrence (YES, NO, ALL, or QUIT)?” prompt is 
displayed on the prompt line. 


e You may answer YES, NO, ALL, or QUIT. 


e If you answer YES, the text is replaced and the VAX RPG II editor 
finds the next occurrence. 


e If you answer NO, the text is not replaced and the VAX RPG II editor 
_ finds the next occurrence. 


e If you answer ALL, the current text is replaced as well as any further 
occurrences of the text, without additional prompting. 


Using the VAX RPG II Editor 2-57 


e If you answer ¢ QUIT, the text is not serepiaced and the SUBSTITUTE 
command terminates. 


¢ If you make any other response, the sequence is repeated from the 
point where the prompt message is displayed. 


If the SYNTAXCHECK option is on, the current line is syntax checked 
after each change is made. If a syntax error is found, the substitution is 
terminated. 


The command does not display the lines on which substitutions are made 
(except in /QUERY mode). 


Upon completion of this command, the message “Substitutions: n” is 
. displayed in the message area, where ‘n’ indicates the number of substitu- 
tions performed. 


Upon completion of this command when the /SELECT qualifier was 
specified, the select range is removed. 


The SUBSTITUTE command i ignores the current editing direction. It 
always proceeds from the beginning of the range to the end. The current 
editing direction is not changed; it is ignored for the duration of the 
command. 


The cursor is returned to where it was before the command was issued. 


Rules for Specifying Search- Argument and 
Replace-Argument 


e The search-argument must contain at least one nonblank character. If 
it does not, the message “The search string must contain at least one 
nonblank character” is displayed i in the message area. 


e If lowercase characters are desired in the substitution, the argu- 
ment must be enclosed within double quotation marks (for example, 
“string”). Otherwise, lowercase characters are converted to uppercase. 


e If the argument contains a terminator, such as a blank space or a slash 
(/), the argument must be enclosed within double quotation marks 
(for example, "“ and "/"). 


e If the argument contains a double quotation mark ("), two double 
quotation marks ("") must be entered. 


¢ Single quotation marks (‘) are not treated like double quotation marks 
(“"). 


¢ Control characters cannot be entered in arguments. 
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2.7 Customizing the VAX RPG II Editor 


This section describes several VAX RPG II editor commands that are 
available to you. These commands enable you to customize your editing 
environment. 


2.7.1 Using Editor Commands 


For the purpose of this example, you want the ruler to lie on the bottom of 
the screen and the HELP keypad to show in the HELP window. Because 
you are entering a program with a compile-time table or array, you want 
to be prompted before any numeric fields are right justified. Because you 
have chosen a small scrolling region, you want the SECTION function to 
give you 10 lines. Finally, you want to use CTRL/P to review errors. 


You would use the COMMAND function (default = PF1/KP7) to enter 
each of the following commands: 

e SET RULER BOTTOM 

e SET SCROLL 2 2 

e SET SECTION 10 

e SET HELP KEYPAD 

e SET SYNTAXCHECK PROMPT 

e DEFINE KEY CTRL_P_KEY REVIEW_ERROR 


See Section 2.6.8.4 for an example of a screen with the ruler on the bottom 
and the HELP keypad displayed. 


2.7.2 Start-up Command Files 


Start-up command files allow you to specify a set of commands to be 
executed automatically each time you begin an editing session. A start-up 
command file can contain any of the VAX RPG II editor commands. It 
can also contain comment and blank lines to improve readability. Each 
command is executed as if the COMMAND function were used. 


The VAX RPG II editor uses the /COMMAND qualifier to find a start-up 
file. This qualifier is present by default, with a default value of RPGINI. 
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The uses of the /COMMAND qualifier and their effects are as follows: 


e §=6If /COMMAND=filespec is used, the specified file is executed. 
e If the /NOCOMMAND qualifier is used, no command file is executed. 


All start-up files are opened with a default file type of RPG. The value for 
the /COMMAND qualifier can be a full or partial file specification, or a 
logical name that translates to a file specification. 


Control can be passed from one start-up file to another by using the 
COMMAND option of the SET command. When the VAX RPG II editor is 
executing commands from a start-up command file and encounters a 

SET COMMAND command, it tries to find the associated file by translat- 
ing logical names, if necessary. If a file is found, the contents of that file 
are then executed in the same way as the original start-up file. The rest of 
the commands in the start-up file are not executed. If the file is not found, 
the rest of the commands in the start-up file are executed. 


Following are several ways of using these options to customize your 
editing environment. 


If you do not want to execute any start-up file, your command line should 
be as follows: 


$ RPG/EDIT/NOCOMMAND filespec 


To execute your own start-up commands, create a file of VAX RPG II 
editor commands and define the logical name RPGINI to reference it. For 
example, create the file MYSTART-UP.RPG to contain the following: 


SET DEFAULT PAGE, PROMPT 

SET HELP KEYPAD 

SET RULER NONE 

DEFINE KEY CTRL_N_KEY REVIEW_ERROR 


Add to your LOGIN.COM file the following: 
$ DEFINE RPGINI MYDISK: [MYDIRECTORY] MYSTARTUP . RPG 


Then, whenever you invoke the VAX RPG II editor, your commands will 
_ be executed. 


One way to establish a customized environment for many users at the 
same time is described here. A system-wide start-up command file can 
be established by defining the logical name RPGINI in the system logical 
name table. In the following example, the file SYSRPGINI.RPG is in the 
directory addressed by SYS$PUBLIC. 
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! System-wide start-up commands 
SET HELP SPECIFICATIONS 

SET RULER BOTTOM 

SET COMMAND RPGINI.RPG 


If RPGINI was defined by the following command then, by default, 

all users on the system would have that set of commands executed 
automatically. The last command shown would mean that after executing 
the system-wide commands, the VAX RPG II editor would also execute 
any commands found in the RPGINIRPG file in the default directory. 


$ DEFINE/SYSTEM RPGINI SYS$PUBLIC:SYSRPGINI.RPG 


2.7.3 Modifying Screen Length 


You can determine the number of lines on the terminal screen that are 
used by the VAX RPG II editor. This is a useful option for a variety of 
reasons. If you have a VT100 terminal that does not have Advanced 
Video Option (AVO), there are only 14 lines in 132-column mode. It 

is also useful if you have a terminal with more than 24 lines. Also, 

if you have a terminal that runs at a slow baud rate, you can control the 
number of lines displayed on the VAX RPG II editor screen. This improves 
performance over a slow communication line by decreasing the number of 
lines on the screen that must be updated during an editing session. 


Use the DCL command SET TERMINAL/PAGE=n to set the length of the 
page on your terminal screen. You can also set the width of the page with 
SET TERMINAL/WIDTH=n. If you set the width to 132 columns, you 
will get the full text of the VAX RPG II editor error messages. 


Note that there must be at least six lines on the screen to allow for the 
two-line ruler, tab stop line, prompt line, message line, and one line in the 
source editing window. 


2.8 Creating and Editing Programs 


This section contains a sample VAX RPG II program and some of the 

output it might produce. Section 2.8.1 shows you how to create a program 
using the VAX RPG II editor, and Section 2.8.2 shows you how to edit 

a program using the VAX RPG II editor. Both sections use the following 

sample program. 
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Note that this example assumes a 24-line screen and no start-up file. 





SSSR SSSR VENTS] GAR Say ESE ana RNS Wee eae ee es ee 
{2345678901 23456789012345678901 2345678901 2345678901 23456789012345678901 234567890 





H¥++ 

H* FUNCTIONAL DESCRIPTION: 

Hx This program produces a report of shipments for various 
H* products broken down by division and department using an 
Hx input file with the shipment data for the past 4 quarters. 


Hx-- 

H 

FSHIPS IP F 44 DISK 

FSUMREP QO F 98 LPRINTER 
E QTY 4 20 


LSUMREP SS5FL SOOL 
ISHIPS AA Of 


I 4 5 DIV Le 
I 6 7 DEPT Li 
I 8 16 PROD 

I 17 24 QTY 

Cx 

Cc «(OL XFOOTQTY PROQTY 30 

Cc «(Of PROQTY ADD DEPQTY DEPQTY 30 

Cx 

CL DEPQTY ADD DIVQTY DIVATY 30 

CLi Z-ADDO DEPQTY 

CL2 DIVQTY ADD FINQTY FINQTY 40 

Cx 
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0) : to \ 2 | 3 r | 5 : 1 6 | 7 "| 
12345678901234567890123456 7890123456 7890123456 7890123456 789012345678901234567890 





OSUMREP H O01 iP 


0 48 "PRODUCT SHIPMENT REPORT’ 
0 H 02 iP 

0 UDATE Y 12 >a 

0 48 ‘PRODUCT SHIPMENT REPORT’ 
0 H 4 iP 

0 42 ‘SHIPMENTS’ 

0 H 2 iP 

0 45 ‘DIVISION DEPT’ 

0 24 ‘PRODUCT’ 

0 48 "Qi Q2 Q3 Q4 TOTAL’ 
0 D 4 041 

0 L2 DIV 8 

0 Li DEPT 14 

0 PROD 25 

0 QTY Z 414 

0 PROQTYZ 48 

0 T 14 Li 

0 T 0 L2 

0 DIV 69 

0 T 0 L2 

0 DIV 69 

0 T 02 L2 

0 DIVQTYZB 48 

0 63 '<== Total for’ 

0 DIV 69 

0 T 0 LR 

0 FINQTYi 48 

0 65 ‘<== GRAND TOTAL’ 
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A sample of the output from this program might appear as follows: 


0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 
9/09/83 PRODUCT SHIPMENT REPORT 
SHIPMENTS 
DIVISION DEPT PRODUCT Q1 Q2 Q3 Q4 TOTAL 
East 12 CPU-19 12 13 14 15 54 


CPU-20 11 11 11 10 43 


13. TERM-12 12 34 34 35 115 
TERM-13 23. 24 25 26 98 
TERM-20 11 12 13 14 50 


360 <== Total for East 
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North 23 DISK-45 18 17 16 14 64 
DISK-48 12 14 20 35 81 
DISK-60 10 10 10 ii 41 


24 TAPE-12 8 7 6 3 24 
TAPE-13 1 2 4 ii 18 
TAPE-32 10 10 10 i1 4i 
TAPE-33 4 4 4 6& 17 


286 <== Total for North 


South 25 MEMORY-11 19 20 21 21 8i 
MEMORY-16 19 18 17 16 70 
MEMORY-17 12 13 13 12 50 


201 <== Total for South 


West 39 SOFT-12 11 13 13 12 49 
SOFT-14 6 7 8 8 29 
SOFT-23 13 14 20 19 66 


40 SOFT-24 15 14 14 13 56 
SOFT-25 3 3 4 7 17 


217 <== Total for West 
1,064 <== GRAND TOTAL 


2.8.1 Creating a New Program 


Invoke the VAX RPG II editor by typing the following command: 
$ RPG/EDIT MYFILE 


The VAX RPG II editor displays the following message: 


File not found 
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The following screen is displayed: 


Of ol fA Oa, REN Uae oh eel oe BR i Pee 
PERT UTTER CYC URERT CYECULERTGCYETITERT CHER USERT GPETIT ERT Gyre ited rice ls 
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Although VAX RPG II does not require a Control specification (see 
Chapter 15 for information on all VAX RPG II specifications), it is use- 
ful to place an asterisk in column 7 of a Control specification to include 

a comment describing what your program does. Press either the TAB 
key or the RIGHT key repeatedly to move the cursor to column 6. Type 
H in column 6. Use the HELP_SPECS function (default = PF1/PF2) to 
display the specification format for the Control specification. Because the 
current line is a Control specification, the VAX RPG II editor automatically 
displays the tab stops for the Control specification. HELP information will 
be displayed in the HELP window of the VAX RPG II editor screen, as 
shown in the following example: 





Currency. symbol 
Inverted print (DIJ) 
| Alternate collating sequence (SE) 
I 1P forms position (1) 





“H (na Al ae 
| 2 | 3 | 4 | 5 | ) | 7 | 
123456 7890123456 789012345678901234567890123456 7890123456 789012345678901234567890 
Lee ee re a A RR ar eR a EE a a 
H 
CEOBI i 
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Enter an asterisk fe ) in column 7. Type the description of the program. 
Press the RETURN key at the end of each line. After the RETURN key is 
pressed, the VAX RPG II editor moves the current line on the screen one 
line up, if necessary; automatically enters H in column 6; and moves the 
cursor to column 7. (Column 7 is the default setting for the 

SET STARTCOLUMN command.) To display the current default for the 
SET STARTCOLUMN command, issue the COMMAND function 

(default = PF1/KP7), type SHOW STARTCOLUMN, and press the 
RETURN key, as shown in the following example: 





Currency symbol 

Inverted print (DIJ): 

| Alternate collating sequence (SE) 
| | 1P forms position (1) 
‘| | | 

| 


| 
| 
| 
| + 

I pea ee. meee Gok a os ss 
| 2 | 3 | 4 | a) | 6 | 7 | 
RASTER LAU SE EN EE CE A er 


Fosse wees ban hee Meae Muss saeses sina My acinnt seit nie says oeae hcietiarsaea Seine 


H¥++ 

H* FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 
H% products broken down by division and department using an 


Hx input file with the shipment data for the past 4 quarters. 
H®-— 








oO | 4 





Hg 
CEOB] 


<PFA/KP7> 





STARTCOLUMN value is: 
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The specification type for the current line will be duplicated until you 
enter a new specification type in column 6. H is automatically entered 

in column 6 and the cursor is moved to column 7. The next specification 
needed is the File Description specification. To replace H, move the cursor 
to column 6 by using the FIELD_BACKWARD function 

(default = BS_KEY), and enter F (File description). 


Enter the name of the file, beginning in column 7, and then use the 
FIELD_FORWARD function, hereafter referred to by its default setting, 
TAB_KEY. Because HELP information is displayed in the HELP window 
of the VAX RPG II editor screen, after TAB_KEY or any terminator is 
pressed the VAX RPG II editor displays the specification format and tab 
stops for the File Description specification, as shown in the following 





example: 
Mode (LR) 
IKey length 
Type (IOUDC) || Record address type (APIB) Addtn(AU) 
IDes(PSRCTDF)1! lOrganization (IT,1-9) xpan 
I1EOF (E) 1} |!Overflow indicator Continue (K) I1Shr(SR) 
111Seq (AD) Il Til Key location }Opt Entry If! Rewnd 
File LULIFmt (FV) Tt dit | | Extension (EL)II | Hitt 
name IVTHIBIK Rec I} It! | Device Symb Tape Core III IFile 
| })ttlen len Tl Vil | Icode dev label index I/II Icond 
FI ee ee | | Hit ou 
0 1 2 | | 
He Pe ae eee eT # Kisewin ¥----- HEX HK. 
H¥++ 


H* FUNCTIONAL DESCRIPTION: 
H* This program produces a report of shipments for various 
H* products broken down by division and department using an 


H% input file with the shipment data for the past 4 quarters. 
H¥-- 


H 
FSHIPS jj 
CEOBI 
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Note that you can press TAB_KEY to move the cursor to the next tab 
stop. Enter the rest of the File Description specifications as shown in the 
following example: 





Ilen len 
| 






Mode (LR) 
IKey length . 
Type (IOUDC) 1! Record address type (APIB) Addtn( AU) 
IDes(PSRCTDF) I! (Organization (IT,1-9) [Expand 
TIEOF (E) 11 [lOverflow indicator Continue (K) | 1Shr(SR) 
[}1Seq (AD) Il Til Key location © JOpt = Entry II! Rewnd 
File P1tiFmt (FY) TH] til t | Extension (EL) 11 | Hil 
name TITTIBIK Reo Tl Tl! | {Device Symb Tape Core III IFile 
| ie Tl} Jtl | leode dev label index a Icond 
1 Ht tilt ptt 










| 4 \ 2 \ 3 4 | 5 | 6 | 7 
12345678901234567890123456789012345678901234567890123456 789012345678901234567890 
#% HEKRHR-—- 8 —— RR HR H--— EE ¥ Sr TT) ee 

H* FUNCTIONAL DESCRIPTION: 

H% This program produces a report of shipments for various 
H# products broken down by division and department using an 
H* input file with the shipment data for the past 4 quarters. 


H*-- 

FSHIPS IP F 41 DISK 
FSUMREP QO F 98 LPRINTER 
Fa 


CEQB] 
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Replace F in column 6 with E (Extension) and press TAB_KEY. The 
VAX RPG II editor displays the specification format and tab stops for 
the Extension specification. Then, enter the rest of the entries for the 
Extension specification, as shown in the following example: 





Sats F = Format (PB) . 
[ aeees D = Decimal positions 
eee = Sequence (AD) 
11 
: ‘IllAlternating table or array 
From To Table EntEnt LenllIname Len 
file file or perin of FIll of F 
name names array RecTbl EntiDIl EntiD 
| | name | | It ISI 1 11s 
E UL i i 1h 7 Ul |} Jtl+-- Comments ---+ 


{ | 3 5 6 ] 7 1 





12345678901234567890123456789012345678901234567890123456789012345678901234567890 
Hovnek # x it eee ee H-— HERE 
Hi This program produces a report of shipments for various 
Hx products broken down by division and department using an 
H% input file with the shipment data for the past 4 quarters. 


H*-- 
FSHIPS. IP F “1 DISK 
FSUMREP QO F 98 LPRINTER 
E gry 4 20 
El 

[EOB] 
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Enter L (Line Counter) in column 6, Then, enter the rest of the entries for 
the Line Counter specification, as shown in the following example: 





Form length (1-112) 
File | FL (if Form length used) 
name 1 | Overflow line number (1-112) 
| 1 It OL Cif Overflow line used) 
LI 1 tt 4 
] 2 3 ] 4 | 5 | 6 7 





0 4 
123456 7890123456 7890123456 78901234567890123456 7890123456 7890123456 78901234567890 
HE H-—* #--% TOLL CCCP eee eee ee eee ee ee 
H¥ products broken down by division and department using an 
input file with the shipment data for the past 4 quarters. 
H¥-- 


FSHIPS IP F ry DISK 
FSUMREP O F 98 LPRINTER 
E 4 20 
LSUMREP SS5FL S00L 
1 

[EOB) 
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Enter the Input specifications, as shown in the following example: 


Sequence (AA-ZZ, 01-99) 
| Number (1-N) 


| [Optional/External (OU) Decimal positions 

| |tRecord identifying indicator | Control level 

1 ut | | Match field 

| tlt + Identifying codes + Format | 1 | Fld rec rel 
File 1 ltl 1 | (PB) Field I} 1 
name ttt | ¢ ¢ Cl iField tname | 1 1! Field 
| : Hit | Z Z Z| {location!| | | | indicatrs 

an 1 | 


Pos NDcPos NDcPos NDc IFr To II +- 9 
| 3 | 





| 1 | é 4 
123456789012345678901234567890123456789012345678901234567 
a a eS er 
E QTY 4 20 
LSUMREP SS5FL 500L 
ISHIPS AA O04 


I 1 SDIV L2 
I 6 7 DEPT Li 
I 8 416 PROD 
I 17 24 QTY 
If 

[EOB] 
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Use the DISPLAY function (default = PF1/KP8) to display the program on 
the entire screen (except lines 1 through 3, 23, and 24), as shown in the 
following example: 





0) I 1 | 2 I 3 | 4 I 5 | 6 | 7 | 
1234567890123456 7890123456 7890123456 78901234567890123456 7890123456 7890123456 7890 
#% HOMKK R---  KR-- 0 RR-- RH ---8--- HH HHH HH K wee 

H¥++ 

H* FUNCTIONAL DESCRIPTION: 

H* This program produces a report of shipments for various 
H# products broken down by division and department using an 
H* input file with the shipment data for the past 4 quarters. 


H*-- 

FSHIPS IP F 41 DISK. 
FSUMREP O F 98 LPRINTER 
E QTY 4 20 


LSUMREP 55FL S5S00L 
ISHIPS AA Of 

I {i 5 DIV Le 
I 6 7 DEPT Li 
I 8 16 PROD 

I 17 24 QTY 

I 


CEOBI 
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Enter the Calculation specifications without displaying the specification 
format in the HELP window, as shown in the following example: 


| 4 | 4) | ) | 7 





0) | 
ERATE LETRA RS LACE LUE UE LT IEE Te Re 
uo R-~ HE Re * 


1 rn ee 
‘HR ¥.. * ° # 
Hke- 

FSHIPS IP F AL 
FSUMREP OF 98 
E QTY 
LSUMREP  S5FL 500L 
ISHIPS AA O01 
I - 
I 
I 
I 
Cx 
Cc (Of XFOOTOTY 
Cc Of PROQTY ADD DEPATY 
Cx 
CLA DEPQTY ADD DIVQTY 
CLi Z-ADDO 
cL2 DIVATY ADD FINQTY 
Cx | 
cl 
[EOB) 
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DISK 
LPRINTER 
4 20 


1 SDIV L2 
6 7 DEPT Li 
8 46 PROD 

17 24 QTY 


PROQTY 
DEPQTY 


DIVOTY 
DEPATY 
FINQTY 


30 
30 


30 
40 
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Enter the Output specifications as shown in the following example. Note 
that the VAX RPG II editor screen can display only 19 source lines at 

a time when the terminal has 24 lines and when the ruler is displayed. 
After you enter more than 19 lines, the VAX RPG II editor moves the 
editing window up. 





0, ss ae dies ae eee teh oe ON ee ae Ge eres 
12345678901234567890123456789012545678901234567890123456789012345678901234567890 
: *¥ | RRR HH ¥% RRR KR i tela see 

OSUMREP H 001 {P| 

0 48 ‘PRODUCT SHIPMENT REPORT’ 

0 H 02 1P : ) 

0 UDATE Y 12 

0 48 ’PRODUCT SHIPMENT REPORT’ 

0 H 4 iP | 

0 | 42 ‘SHIPMENTS’ 

0 H 2 iP 

0 15 'DIVISION DEPT’ 

0 24 "PRODUCT? 

0 48 1 G2 @3 4 TOTAL’ 

0 D1 04 

0 DIV g 

0 Li DEPT 14 

0 PROD 25 

0 Qty Zz 44 

0 PROQTYZ 48 

0 T 4 Li , 

HI 
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Enter the rest of the Output specifications. Use the EXIT function 

(default = CTRL_Z_KEY) to save the contents of the editing buffer and to 
leave the VAX RPG II editor. When EXIT is used, the VAX RPG II editor 
displays the following message as shown in the next example: 


45 records written to file MYDISK: [MYDIRECTORY]MYFILE.RPG;1 





0 


oooococoo0n eo e000 ec ecMeo a 





$f 


HRRERK H% % 
H 02 iP 
H 4 1P 
H 2 iP 
D4 04 
Li 
Ta Li 
TO LR 
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0 | 4 | 2 | 3 | 4 | 5 | 3) | ? | 
123456789012345678901234567890123456789012345678901234567890123456 78901234567890 
#% 





* RXE-—-~- HE ‘eae 
UDATE Y 42 | 
48 PRODUCT SHIPMENT REPORT’ 
42 SHIPMENTS’ 
45 'DIVISION DEPT’ 
24 'PRODUCT? 
48 Qi Q2 G3 04 TOTAL’ 
DIV 8 
DEPT 14 
PROD 25 
QTY Z 44 
PROQTYZ 48 
FINGTY’ 48 
65 ’<== GRAND TOTAL’ 


45 records written to file MYDISK: [CMYDIRECTORYIMYFILE.RPG; 4 
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2.8.2 Editing an Existing Program 


When you invoke the VAX RPG II editor to edit the program created in 
Section 2.8.1, the VAX RPG II editor displays the following message: 


45 records read from file MYDISK: [MYDIRECTORY]MYFILE.RPG;1 


The following screen is displayed: 





0 | 4 \ 2 | 3 | 4 | 5 ] 6 7 | 

1234567890123456 7890123456 789012345678901234567890123456789012345678901234567890 
- Rac rncnnncna koe koncaKncncccevesesccteseneenevcecerseesssseesnsnvcseee 

# H¥++ 

Hx FUNCTIONAL DESCRIPTION: 

H* This program produces a report of shipments for various 

Hk products broken down by division and department using an 

H* input file with the shipment data for the past 4 quarters. 





He-- 
H 

FSHIPS IP F re DISK 

FSUMREP OF 98 LPRINTER 
E QTY 4 20 


LSUMREP 55FL 500L 
ISHIPS AA Of 


I 4 5 DIV Le 
I 6 7 DEPT Li 
I 8 16 PROD 

I 17 24 QTY 

Cx 

Cc «(Of XFOOTQTY PROQTY 30 

Cc Of PROQTY ADD DEPQTY DEPQTY 30 


Press the PFe key to get 





information 
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In this session, the control-level indicator L2 must condition the DIV field 
in the detail record Output specification. Use the FIND function 
(default = PF1/PF3) to locate DIV. The VAX RPG II editor displays the 
command prompt “Search for: ”. Enter the search string DIV and press: 
the ENTER key, as shown in the following example: 








4 | 2 | 4 | 4) | 6 | ? | 
1234567890123456 7890123456 78901 2345678901 2345678901 23456 7890123456 78901234567890 


Reeve cce nea ke ake cake cncncccseennakessceessceteensseeueneesesensaugs 


H¥++ 

H* FUNCTIONAL DESCRIPTION: . 
H# This program produces a report of shipments for various 
H* products broken down by division and department using an 
H¥ input file with the shipment data for the past 4 quarters. 





H#-- 

H 

FSHIPS IP F re DISK 

FSUNREP O F 98 LPRINTER 
E QTY 4 20 


LSUMREP 55SFL SO0OL 
ISHIPS AA O14 


I { 5 DIV Le 
I 6 7 DEPT Li 
I 8 16 PROD 

I 17 24 QTY 

C¥ 

Cc (Of XFOOTQTY PROQTY 30 

C Ol PROQTY ADD DEPQTY DEPQTY 30 


Search for: DIV 
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The VAX RPG II editor responds by moving the cursor to the first charac- 
ter of the first occurrence of the search string DIV (see the comment line), 
as shown in the following example: 








0 | 1 | 2 | 3 | 4 | 5 | ) | 7 | 
1234567890123456789012345678901234567890123456 7890123456 789012345678901234567890 
Jere res Tee Lee ETE ee EET EEE ee Eee 
He++ 
H* FUNCTIONAL DESCRIPTION: 

H* This program produces a report of shipments for various 
H# products broken down by fjivision and department using an 
Hi input file with the shipment data for the past 4 quarters. 


H*-— 

H 

FSHIPS IP F 44 DISK 
FSUMREP OO F 98 LPRINTER 
E QTY 4 20 


LSUMREP 55FL S500L 
ISHIPS AA 01 


I 4 5 DIV Le 
I 6 7 DEPT Li 
I 8 16 PROD 

I 17 24 QTY 

Cx 

Cc Of XFOOTQTY PROQTY 30 

C Of PROQTY ADD DEPQTY DEPQTY 30 
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Because this is not the correct string, use the FIND_NEXT function 
(default = PF3). The VAX RPG II editor moves the cursor to the first 
character of the next occurrence of the string DIV, as shown in the 
following example: _ 


Oa ow ae ae eT, eee Sen ee eh Ge n= a 
12345678901234567890123456789012345678901254567890123456789012345678901234567890 
H% x HRX R--- ¥--- f--— Met Seteteet Setetet 5.9 eH HHH HR aces . 

H¥++ 





H* FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 
Hx products broken down by division and department using an 
H* input file with the shipment data for the past 4 quarters. 


Hx¥-- 

H 

FSHIPS IP F 44 DISK 

FSUMREP QO F 98 LPRINTER 

E _ QTY 4 20 

LSUMREP 55FL 500L 

ISHIPS AA Ol 

I 1 SIv L2 
I 6 7 DEPT Lif 
I 8 416 PROD 

I 17 24 QTY 

Cx : 

Cc «Of ; XFOOTOTY PROQTY 30 

C 


of PROQTY ADD DEPQTY DEPQTY 30 
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) I it i 2 | 3 | 4 | 5 I a) | 7 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 





H 
Cc «(Ol 
Cx 
CLi 
CLi 
CL2 


Again, this occurrence of the string DIV is incorrect, so issue the 
FIND_NEXT function five more times to move the cursor to the correct 
occurrence. You could have specified DIV and a blank as the search string 
to avoid duplicating key strokes. L2 must be entered in columns 24 and 
25. To do this, move the cursor to column 24 by pressing BS_KEY to 
column 23, then use the RIGHT function (default = RIGHT) once. Enter 
the string L2 in columns 24 and 25, as shown in the following example: 


KEKRE HK % H¥K——- HH aoe 
PROQTY ADD DEPQTY DEPQTY 30 


DEPQTY ADD DIVQTY  DIVQTY 30 
Z-ADDO DEPQTY 
DIVQTY ADD FINQTY FINQTY 40 


C% 
OSUMREP H O04 1P 


ooo0o0d0ecea0nM00nd 


48 ’PRODUCT SHIPMENT REPORT’ 


H02  4P 
UDATE Y 12 
48 ’PRODUCT SHIPMENT REPORT’ 
H 4  4P 
42 'SHIPMENTS’ 
H 2 4p 
15 ‘DIVISION DEPT’ 
24 ‘PRODUCT’ 
48 01 G2 O3 @4 TOTAL’ 
Di of 
Lag sv 8 
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490C = Of 


240C% 


2600 
2700 
2800 
2900 
3000 
3100 
3200 
3300 
3400 
3500 
3600 
3700 


Command: RESEQUENCE 


Number the program lines for reference by issuing the COMMAND 
function (default = PF1/KP7) and typing the RESEQUENCE command, as 
shown in the following example: 


H 02 


D1 


| | 2 3 | 4 | 5 | Ls) | 7 
4567890123456 7890123456 7890123456 7890123456 78901 2345678901234567890 
EE 
PROQTY 
DEPQTY 
DIVQTY 


2500SUMREP H 001 





, ¥ REX—-—— HE . aeons 
ADD DEPQTY DEPQTY 30 
ADD DIVQTY DIVQTY 30 
Z-ADDO DEPQTY 
ADD FINQTY FINQTY 40 
iP 
48 ’PRODUCT SHIPMENT REPORT’ 
4P . 
UDATE Y ie 
48 ’PRODUCT SHIPMENT REPORT’ 
iP 
42 ‘SHIPMENTS’ 
iP 
45 ’DIVISION DEPT’ 
24 ‘PRODUCT’ 
48 Qi Q2 Q3 4 TOTAL’ 
04 
Le# DIV 8 


2-82 Using the VAX RPG Il Editor 


ZK-4373-85 


Use the SECTION function (default = KP8) to move the cursor the number 
of lines set by the SET SECTION command, as shown in the following 
example: 





0 | 4 | 2 3 4 | 5 | 6 I 7 | 

12345678901234567890123456789012345678901234567890125456789012345678901234567890 

i ee # RRR HE aaa 

2800 UDATE Y 12 

2900 48 “PRODUCT SHIPMENT REPORT’ 

3000 H 1 iP 

3100 42 ‘SHIPMENTS’ 

3200 H 2 iP . 

3300 45 ’DIVISION DEPT’ 

3400 24 ‘PRODUCT’ 

3500 48 ‘01 Q2 Q3 Q4 TOTAL’ 

3600 Di O41 

3700 L2 DIV 8 

3800 Li DEPT 414 

3900 PROD 25 

4000 QTY Z 41 

4100 PROQTYZ 48 

4200 T 1 Li . 

4300 T 0 LR 

4400 FINQTY£ 48 

4500 | 65 ‘<== GRAND TOTAL’ 
CEOBI 


Attempt to..move past end of buffer 
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Enter two Output specifications between lines 420 and 430 by using the 


following functions: 


UP (default = UP) to line 430 


1. 


2. OPEN_LINE (default = PF1/KPO0) to create a new line 


Use the OPEN_LINE function to create a line preceding the current line. 
The VAX RPG II editor automatically places the specification type of the 
current line in column 6 and moves the cursor to column 7, Enter the new 
specifications, as shown in the following example: 





3000 H 
3200 H 
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4 
2 


iP 
iP 


04 
Li 


Li 
L2 


LR 


0 | | | 2 | 3 4 | 5 | 6 | 7 
123456789012345678901234567890123456 7890123456 78901234567890123456 7890123456 7890 
#% HERKE HH 


% RKE——-— HH peas 
48 "PRODUCT SHIPMENT REPORT’ 
42 ’SHIPMENTS’ 
15 DIVISION DEPT’ 
24 ‘PRODUCT’ 
48 "01 Q@2 Q3 04 TOTAL’ 
DIV 8 
DEPT 14 
PROD 25 
QTY Z 41 
PROQTYZ 48 
DIV x) | 
FINQTYi 48 
65 ’<== GRAND TOTAL’ 
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Enter two more specifications (identical to the two specifications just 
entered) by using the following functions: 


r, 


2. 
3. 
4, 


SELECT (default = PERIOD) to mark the beginning of the selected 
region 


UP (default = UP) once 
CUT (default = KP6) to place the selected region into the paste buffer 
PASTE (default = PF1/KP6) twice 


The following example shows the effects of the procedure just described: 





1) | 1 | ra | 3 4 | a) 6 | 7 7 
£25056 7890123456 78901 23456 7890125456 7890123456 7890123456 7890125456 78901234567850 


HHERE % % ae ‘HER-—— HE ee Sea a 
48 'PRODUCT SHIPMENT REPORT! 
H i 4P | 
| 42 'SHIPMENTS’ 
H 2  4P 
15 "DIVISION DEPT’ 
24 "PRODUCT! 
48 'Q1 O2 3 04 TOTAL’ 
Di Of 
L2 DIV 8 
Lf DEPT 14 
PROD 25 
aTy Z 4 
PROQTYZ 48 
T 1 Lt 
TO 1-2 
DIV 69 
TO L2 
DIV 69 
TO LR a 
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Enter four more specifications. Then, remove ine line numbers, as shown 
in the following example: 





aT ee a aa Es en a ead es er ee eee as ee 
123456 789012345678901 23456 7890123456 7890123456 7890123456 7890123456 78901254567890 





RX HERRE HH HO RRR mR cree. 
0 H 2 iP 

0 15 ‘DIVISION DEPT’ 

0 24 ’PRODUCT’ 

0 48 'Q1° Q2 Q3 Q4 TOTAL’ 
0 Di 04 

0 L2 DIV 8 

0 Li DEPT 14 

0 PROD 25 

0 QTY Z 41 

0 PROQTYZ 48 

0 T i L4 

0 T 0 L2 

0 DIV 69 

0. T 0 L2 

0 DIV 69 

0 T 02 L2 

0 DIVQTYZB 48 

0 | 63 ‘<= Total for’ 

0 DIV 69§ 


Command: RESEQUENCE/REMOVE 
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Use the COMMAND function and type the EXIT command to save the 
modified program, as shown in the following example: 






12345678901 23456 7890123456 78901 2.3456 7890123456 7890123456 78901254567890123456/890 


#* HHKER H % % HER —— 8H sae 
0 H 2 iP 

0 45 ‘DIVISION DEPT’ 

0 24 'PRODUCT’ 

0 48 701 Q2 Q3 Q4 TOTAL’ 
0 Di 04 . 

0 L2 DIV. 8 

0 Li DEPT i4 

0 PROD 25 

0 QTY Z 441 

0 PROQTYZ 48 

0 T 4 Li 

0 T 0 L2 

0 DIV 69 

0 T 0 L2 

0 DIV 69 

0 T 02 L2 

0 DIVQTYZB 48 

0 63 ’<== Total for’ 

0 DIV 698 
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Chapter 3 


Processing VAX RPG II Programs 


You can create a source program using the VAX RPG II editor; then, 

you must compile, link, and run the program with commands to the 
VAX/VMS operating system. You can optionally create an object file be- 
fore leaving the VAX RPG II editor using the VAX RPG II editor COMPILE 
command. If your VAX RPG II program does not execute correctly, you 
must modify it and repeat these steps until it does. 


When you compile a VAX RPG II program, the VAX RPG II compiler 
creates an object module file. When you link your program, use the 
VAX/VMS Linker. The linker reads the object module file and uses 
libraries to replace external references with the address of the executable 
code that defines it. Then the linker places that code in an executable 
image file. When you execute your program, the system executes that 
image. 


3.1 Compiling Programs 


To compile a source program, use the RPG command as follows. 
$ RPG[/qualifier(s)] file-spec-list [{/qualifier(s)] 
/qualifier(s) 


Specifies special actions the compiler is to perform. See Sections 3.1.2.1 
through 3.1.2.8 for information on qualifiers. 
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file-spec-list 

Specifies the source files to be compiled. Normally, you would specify, a 
single source file, but if you need to create a single object file from more 
than one source file, separate the file specifications with plus (+) signs. 
VAX RPG II appends the files in the order you specify. If you separate 
source file specifications with commas, VAX RPG II compiles the programs 
separately and creates a single object file for each source file. 


When you execute the RPG command, VAX RPG II compiles the program 
and generates an object module with the specified file name and the 
default file type OBJ. The compiler can also generate other output files, 
depending on the qualifiers you supply. 


When you compile a source file and specify only its file name, the com- 
piler searches for a source file with the specified name that is stored on 
the default device in the default directory and has a file type of RPG. 


If more than one file meets these conditions, the compiler chooses the one 
with the highest version number. 


For example, assume that your default device is DBAO:, your default 
directory is [SMITH], and you give this command: 


$ RPG FIRSTTRY 
$ 


The appearance of the second DCL command prompt ($) indicates that 
the compilation is finished. 


The compiler searches device DBAO: in directory [SMITH], seeking the 
highest version of FIRSTTRY.RPG. If you do not specify an output file, the 
compiler generates the file FIRSTTRY.OBJ and stores it on device DBAO: 
in directory [SMITH], with a version number that is one higher than any 
existing version number for FIRSTTRY.OB)J. 


3.1.1 Default Compiler Options 


3-2 


When you compile a program, you can specify optional qualifiers such 
as /LIST or /NOWARNINGS. The qualifiers you get when you do not 
specify them are called defaults. 


You can change these defaults for your own programs by using qualifiers 
with the RPG command. The RPG command accepts qualifiers to change 
the defaults for a single compilation, as shown in the following example: 


$ RPG/LIST/NOOBJECT MYPROG 
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This RPG command instructs VAX RPG II to compile a single source file 
(MYPROG.RPG) and overrides the default compiler settings for: 


e  Listing—the VAX RPG II compiler will produce a compiler listing. 

e Object file—the VAX RPG II compiler will not produce an object file. 
You can specify other defaults by defining RPG as a symbol, as shown in 
the following example: 

$ RPG :== "RPG/CHECK/LIST/CROSS" 


If you then type RPG MYPROG, the /CHECK, /LIST, and /CROSS 
qualifiers are in effect. 


3.1.2 Compiler Qualifiers 


This section describes the RPG command; Sections 3.1.2.1 through 3.1.2.8 © 
describe the RPG command qualifiers and list their default values. 


You can change defaults by using qualifiers with the RPG command. 
Qualifiers have the form: 


/qualifier [=value] 


Many qualifiers have a corresponding form that negates the action speci- 
fied by the qualifier. The negative form is as follows: 


/NOqualifier 


For example, /LIST tells the compiler to produce a listing file; /NOLIST 
suppresses the listing. 


You can specify qualifiers so that they affect either all files in the com- 
mand, or only certain files. If the qualifier immediately follows the RPG 
command, it applies to all files, as shown in the following example: 


- $ RPG/LIST ABC, XYZ,RST 


This command specifies listing files for ABC.RPG, XYZ.RPG, and 
RST.RPG. 


Qualifiers following a file specification (with some exceptions) affect only 
the associated file, as shown in the following example: 


$ RPG/LIST ABC, XYZ/NOLIST,RST 
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The preceding RPG command specifies listing files for ABC.RPG and 
RST.RPG, but not for XYZ.RPG. Qualifiers to a single file specification in 
an appended list of file specifications are exceptions to this rule. (A list of 
file specifications separated by plus signs (+) is called an appended list or 
plus list.) See Example 5 in the following list. 


1. 


$ RPG/LIST AAA,BBB,CCC 


VAX RPG II compiles source files AAA.RPG, BBB.RPG, and CCC.RPG 
as separate files and produces three object files (AAA.OBJ, BBB.OBJ, 
and CCC.OBJ) and three listing files (AAA.LIS, BBB.LIS, and 
CCC.LIS). 


$ RPG XXX+YYY+ZZZ 


VAX RPG II appends source files XXX.RPG, YYY.RPG, and ZZZ.RPG 
and compiles them as a single program. This command produces one 
object file named XXX.OBJ, but does not produce a listing file. 


$ RPG/OBJECT=SQUARE CIRCLE 


VAX RPG II compiles source file CIRCLE.RPG and produces object file 
SQUARE.OBJ. This command produces no listing file. 


$ RPG AAA+BBB,CCC/LIST 


VAX RPG II produces two object files: AAA.OBJ (created from 
AAA.RPG and BBB.RPG) and CCC.OBJ (created from CCC.RPG). 
VAX RPG II also produces the listing file CCC.LIS. 


$ RPG ABC+DEF /NOOBJECT+XYZ 


VAX RPG II appends and compiles the source files ABC.RPG, 
DEF.RPG, and XYZ.RPG. Because qualifiers in a list of appended 
files affect all files in the list, this command suppresses the creation of 
an object file. 


Table 3-1 lists the qualifiers you can use with the RPG command. 
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Table 3-1: VAX RPG Il Command Qualifiers 


| Qualifier - Negative Form 
/CHECK=[NO]JBOUNDS /NOCHECK 
(NO]JRECURSION 
([NO]BLANKS_IN— NUMERICS 
ALL 
NONE 
/CROSS_REFERENCE /NOCROSS_REFERENCE 
/DEBUG=[NO]SYMBOLS /NODEBUG © 
{NO]JTRACEBACK 
ALL 
NONE 
/LIST[=file-spec] /NOLIST 
/MACHINE—CODE /NOMACHINE—CODE 
/OBJECT[Ffile-spec] /NOOBJECT 
/SEQUENCE_CHECK /NOSEQUENCE—CHECK. 
/WARNINGS=[NOJOTHER : /NOWARNINGS | 
[NO]INFORMATION 
ALL 
NONE 


Default. 
{NOCHECK 


/NOCROSS__.REFERENCE 


/DEBUG= 
(NOSYMBOLS, 
TRACEBACK) 


/NOLIST (interactive) 
/LIST (batch) 


/NOMACHINE_CODE 
/OBJECT 
/NOSEQUENCE_— CHECK 
/WARNINGS= 
(OTHER, 
NOINFORMATION) 


Sections 3.1.2.1 through 3.1.2.8. describe VAX RPG II command. qualifiers 


in detail. 


3.1.2.1 


/CHECK Qualifier 


The /CHECK qualifier causes VAX RPG II to generate code to check 

for run-time errors in array indexes, recursive calls to subroutines, and 
blanks in overpunched numeric fields. The /CHECK qualifier format is as 
follows: 


/CHECK {=(option[,...])] 
option 
Can be one of the following: 
e [NO]JBOUNDS 


¢ [NOJRECURSION 
¢  [NO]BLANKS_IN_NUMERICS 


e ALL 
e NONE 
BOUNDS 


Checks array indexes at run time to make sure they are within array 
boundaries specified by the program. 


RECURSION | 
Verifies at run time that subroutines are not called recursively. 


BLANKS_IN_NUMERICS 

Converts blanks in overpunched numeric fields to zeros at run time. This 
option is the default if the program contains a WORKSTN file. Use the 
RPG/CHECK=BLANKS_IN_NUMERICS command to convert blanks in 
riumeric data to zeros if you run your program and receive the following 
message: 


A numeric field contains invalid data 


ALL | 
Indicates that RECURSION, BOUNDS, and BLANKS_IN—_NUMERICS 
checking will be performed. 


NONE 


Indicates that RECURSION, BOUNDS, and BLANKS_IN__NUMERICS 
checking will not be performed. 
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- Specifying the /CHECK qualifier is equivalent to specifying /CHECK=ALL,; 
/NOCHECK is equivalent to /CHECK=NONE. The /NOCHECK qualifier 
is the default. 


Use /CHECK=(RECURSION,BOUNDS) for programs only during initial 
program debugging, because compiling with this qualifier results in 
additional code and, consequently, takes more time to process. Using 
/NOCHECK means that no error will be signaled at run time for an array 
reference outside the bounds of an array or for a subroutine that has 
been called recursively. Therefore, using /NOCHECK may result in your 
program getting a memory-management or access-violation error at run 
time. 


3.1.2.2 /CROSS_REFERENCE Qualifier 


The /CROSS_REFERENCE qualifier causes the compiler to include 
cross-reference information in the listing file for the compiled source 
file. Cross-reference information lists variable names, indicators, and the 
program lines on which they were referenced. Its format is as follows: 


/CROSS_REFERENCE 


When you use the /CROSS_REFERENCE qualifier, you must also use 
the /LIST qualifier, or /LIST must be in effect (default for batch mode) 
to produce a listing file. The /NOCROSS_REFERENCE qualifier is the 
default. 


3.1.2.3 /DEBUG Qualifier 


The /DEBUG qualifier causes the compiler to provide information for the 
VAX/VMS Debugger and the system run-time error traceback mechanism. 
Its format is as follows: 


/DEBUG [=(option[,...])] 
option 
Can be one of the following: 


¢ [NOJSYMBOLS _ 
¢ [NO]TRACEBACK 
e ALL 

¢ NONE 
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s YMBOLS 

Causes the compiler to provide the debugger with local symbol definitions 
for user-defined names (including dimension information for arrays). If 
you use SYMBOLS, you can refer to data entities by their names when 
you use the debugger. 

TRACEBACK 

Causes the compiler to provide an address correlation table so that the 


debugger and the run-time error traceback mechanism can translate 
absolute addresses into source program routine names and line numbers. 


ALL 
Causes the compiler to provide both local symbol} definitions and an 
address correlation table. 


NONE 
Prevents the compiler from providing debugging information. 


Neither the / TRACEBACK qualifier nor the /SYMBOLS qualifier affects a 
program's executable code. 


Specifying the /DEBUG qualifier is equivalent to specifying /DEBUG=ALL; 
/NODEBUG is equivalent to /DEBUG=NONE. The /DEBUG=TRACEBACK 
qualifier i is the default. For information on debugging, see Chapter 5. 





3.1.2.4 /LIST Qualifier 


The /LIST qualifier controls whether VAX RPG II produces a listing file 
for the compiled program. The listing file contains the source program and 
a compilation summary. If you also use the /MACHINE_CODE qualifier, 
the listing file will include the compiler-generated object code for the 
compiled program. If you also use the /CROSS_REFERENCE qualifier, 
the listing file will include cross-reference information. The format of the 
/LIST qualifier i is as follows: 


/LIST [=file-spec] 


You can include a file specification for the listing file. Otherwise, the 
output file defaults to the name of the first source file and the file type 
LIS. 


If the RPG command is executed in interactive mode, the default qualifier 
is /NOLIST. If the RPG command is executed in batch mode, the default 
qualifier is /LIST. 
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The listing file uses a listing page length which depends on the logical 
SYS$LP_LINES. Any value between 30 and 255 can be used for 
SYS$LP_LINES. The listing page length uses three-line top and bottom 
margins. If the logical SYS$LP_LINES is not defined, the default page 
length will be 66 lines (60 listing lines after the three-line top and bottom 
margins are subtracted). 


It is possible to enter nonprintable characters when using an editor other 
than the VAX RPG II editor to create or edit a program. If a source line 

in the compiler listing contains one or more periods (.) where you have 
not entered a period on the program line, it is because the program line 

contains a nonprintable character (for example, a TAB character or a null 
character). 


3.1.2.5 /MACHINE_CODE Qualifier 
The /MACHINE_CODE qualifier specifies that the listing file include the 
compiler-generated object code. Its format is as follows: 
/MACHINE_CODE 


When you use the /MACHINE_CODE qualifier, you must also use the 
/LIST qualifier, or /LIST must be in effect (default for batch mode) to 
produce a listing file. The /NOMACHINE_CODE qualifier is the default. 


3.1.2.6 /OBJECT Qualifier 
The /OBJECT qualifier causes VAX RPG II to produce an object module 
and optionally specifies its file name. Its format is as follows: 
/OBJECT [=file-spec] 
The default qualifier is /OBJECT. 
By default, the compiler generates object files as follows: 


e If you specify one source file, VAX RPG II generates one object file. 


e If you specify multiple source files separated by plus signs (+), VAX 
RPG II appends the files and generates one object file. 


e If you specify multiple source files separated by commas (,), VAX 
RPG II compiles and generates a separate object file for each source 
file. 


You can use both plus signs (+) and commas (,) in the same command 


line to produce different combinations of appended and separated object 
files. See Examples 1 through 5 in Section 3.1.2. 
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To produce an object file with an explicit file specification, you must use 
the /OBJECT qualifier in the form /OBJECT=file-spec. Otherwise, the 
object file has the same name as its corresponding source file and the 
default file type OBJ. By default, the object file produced from appended 
source files has the name of the first source file specified. All other file 
specification attributes (node, device, directory, and version number) 
assume the default values. 


During the early stages of program development, you may find it useful to 
suppress the production of object files until your source program compiles 
without errors. Use the /NOOBJECT qualifier to do this. 


3.1.2.7 /SEQUENCE_CHECK Qualifier 


The /SEQUENCE_CHECK qualifier causes the compiler to check the line 
numbers in columns 1 through 5 of every program line to make sure they 
are in ascending line-number sequence. If the line numbers are not in 

sequence, the compiler issues a warning message. Its format is as follows: 


/SEQUENCE_CHECK 
The /NOSEQUENCE_.CHECK qualifier is the default. 


3.1.2.8 /WARNINGS Qualifier 


The /WARNINGS qualifier allows you to specify whether VAX RPG II 
displays informational and warning messages. Its format is as follows: 


/WARNINGS [=(option[,...])] 
option 
Can be one of the following: 


e [NOJOTHER 
e [NO]JINFORMATION 


e ALL 
e NONE 
OTHER 


Causes VAX RPG II to display warning messages. 


INFORMATION 
Causes VAX RPG II to display informational messages. 
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ALL 
Causes VAX RPG II to display both warning and informational messages. 


NONE | 

Prevents VAX RPG II from displaying warning or informational messages. 
Specifying the /WARNINGS qualifier is equivalent to specifying 
/WARNINGS=ALL; /NOWARNINGS is equivalent to /WARNINGS=NONE. 
The /WARNINGS= (NOINFORMATION,OTHER) qualifier is the default. 


For information on how /WARNINGS affects the VAX RPG II editor 
SYNTAXCHECK option, see also Section 2.6.8.8. 


3.2 Linking and Running Programs 


The VAX/VMS Linker uses the object module produced by the VAX RPG 
II compiler as input and produces an executable image file as output. This 
file has the same name as your program and the default file type EXE. 


When your program calls other programs—that is, when it is comprised 
of more than one program module—the linker takes multiple object files 
and creates a single executable image from them. For information on 
subprograms, see Section 12.6. 


You use the LINK command to invoke the VAX/VMS Linker. The format 
of the LINK command is as follows: 


LINK [/command-qualifier(s)] file-spec-list[/file-qualifier(s)] 


command-qualifier(s) 

Specifies output file options. Use the /DEBUG qualifier to provide infor- 
mation for the VAX/VMS Debugger. See Chapter 5 for information on 
debugging VAX RPG II programs. For information about other command 
qualifiers, see the VAX/VMS Linker Reference Manual. 


file-spec-list 
Specifies a file or the files to be linked. 


file-qualifier(s) 


Specifies input file options. For information on file qualifiers, see the 
VAX/VMS Linker Reference Manual. 
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When you type LINK, the system prompts with: 
File: 


Respond by typing the file specifications. If multiple file specifications do 
not fit on a single line, type a hyphen (-—) as the last character on the line 
and continue on the next line. 


For example, to link the object file created from the program FIRSTTRY in 
Section 3.1, type: 


$ LINK FIRSTTRY 
$ 


NOTE 


If you link a program with a WORKSTN file and get a message 
that FDV$ATERM is undefined, you are attempting to link on a 
system that does not have the VAX Forms Management System 
(VAX FMS) installed. 


This command tells the linker to accept FIRSTTRY.OB] as input and to 
produce FIRSTTRY.EXE as output. After the executable file has been 
created, you run it with the RUN command: 


$ RUN FIRSTTRY 
$ 


NOTE 


If you run a program with a WORKSTN file and get a message 
that there was an error activating FOVSHR, you are attempting 
to run a WORKSTN program on a system that does not have 
the VAX FMS Form Driver installed. 


3.3 Interpreting Compiler Error Messages 


The format of a VAX RPG II compiler error message is as follows: 


fac-severity-IDENT 
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fac . 
Represents the facility. The facility is always RPG. 


severity 
Indicates the severity of the error, which can be I (information), W (warn- 
ing), E (error), or F (fatal). 


IDENT 
Represents the IDENT field. 


The IDENT field of a VAX RPG II compiler error message designates the 
error recovery action taken by the VAX RPG II compiler. IDENT fields can 
have one of the following values: 


° SPEC_IGNORED 


The current specification is ignored. The resulting program, if nonfa- 
tal, executes as if the specification were not entered. 


e ENTRY_IGNORED 


The entry in the current field is ignored. The resulting program, if 
nonfatal, « executes as if the field were blank. 


° DEFN_IGNORED 


The current definition of this field is ignored. The resulting program, 
if nonfatal, uses the previous definition. 


¢ CHAR IGNORED 


The current character is ignored. The resulting program, if nonfatal, 
executes as if the column were blank. 


e =FATAL 


No error recovery action can be taken. The severity level is aways 
fatal. 


¢ ACCEPTED 


The compiler accepts the entry exactly as specified. 
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° SEE_MESSAGE 


The error text contains the recovery action taken by the VAX RPG II 
compiler. 


e 0_ASSUMED 


The entry in the current field is ignored. The resulting program, if 
nonfatal, executes as if the field contained 0. 
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Chapter 4 
Interpreting a Compiler Listing 


This chapter explains the parts of a full compiler listing. The sample listing 
in Figure 4-1 is for the program shown under the Source Listing title. The 
circled numbers on the program listing correspond to the numbered key 
which follows the figure. | 
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Hurjsi7 sapdwioy e Burjaidiayu; 


Figure 4-1: 


sHips @ - 
Source Listing 


a | 


OWMDNOAL WH 


6} 1 


2 3 


-Sample Compiler Listing 


4 


@ 28-Jun-1986 15:58:45 
@ 28-Jun-1986 15:56:12 


5: 6 Yee 


’ VAX RPG: II V2.4 


o 


RPG$: oo :RPG] SHIPS -RPG;1 (1) 


8 


12345678901234567890123456789012345678901234567890123456789012345678901234567890 


H*++ 


H*. FUNCTIONAL DESCRIPTION: 


. He This program produces a report of shipments. for various . 
H+ products. broken down by division and department using. an 
H* input file with the shipment. data. for the past 4 quarters. 
H*-- 

H 
FSHIPS IP F . 41 DISK 

. FSUMREP. 0 F 98 © LPRINTER 
E QTY 4 20 

’ LSUMREP. 55FL 500L 
ISHIPS AA O1 
I 1 S&S DIV. L2- 

I 6 7 DEPT Li- 
I 8 16-PROD 
I 17 . 24 QTY 
C* 

Cc oO! XFOOTQTY PROQTY 30° 

Cc O01 -PROQTY. ADD- DEPQTY DEPQTY 30. 

C* F 

CL1 DEPQTY ADD . DIVQTY DIVQTY 30 . 
CL1 Z-ADDO DEPQTY 

CL2 . DIVQTY ADD. FINQTY- FINQTY 40 

C* 


Page 


1 


€-p Gunsiy sajidwoy e Bunaidiayyy 


OSUMREP H 001 


oqooooooo0o0o0coocooo0oooo0o0o0o0coe°co0o0ooo°cna 


H 02 


iP 


iP 


iP 


iP 


o1 


Li 


Li 
L2 


L2 


L2 


LR 


UDATE Y 


DIV 
DEPT 
PROD 
QTY 2Z 
PROQTYZ 
DIV 
DIV 
DIVQTYZB 
DIV 


FINQTY1 


48 ‘PRODUCT SHIPMENT REPORT' 


12 
48 ‘PRODUCT SHIPMENT REPORT' 


42 ‘SHIPMENTS' 


15 "DIVISION DEPT' 
24 'PRODUCT' 
48 'Qi Q2 Q3 Q4 TOTAL' 


14 
25 
41 
48 


69 

69 

48 - 

63 '<== Total for' 


69 


48 
65 '<== GRAND TOTAL' 


(Continued on next page) 


v-v 


Gust] saidwog e burardiayuy 


Figure 4—1 (Cont.): 


SHIPS 


Machine Code Listing © 


00000000 


- 00000008 


00000010 
00000020 
00000028 
00000030 
0000003C 


-00000040 


00000044 
00000048 
0000004C 
00000050 
00000054 
00000058 
0000005C 


.BYTE 
.BYTE 
. BYTE 
.BYTE 
. BYTE 
.BYTE 
-BYTE 
. LONG 
. ADDRESS 
. ADDRESS 
. ADDRESS 
. LONG 
. ADDRESS 
- LONG 
- LONG 
. ADDRESS 
- LONG 
. ADDRESS 
- LONG 
- LONG 
. ADDRESS 
- LONG 
. ADDRESS 
- LONG 
- LONG 
. ADDRESS 
- LONG 
. ADDRESS 
- LONG 
. LONG 
. ADDRESS 


Sample Compiler Listing 


“X53, “X48, “X49, “X50, “X53 


“X53, °X55,“X4D, “X52, °X45, 
“X47 ,°X06, “X02, “X40, 7X20, 
“X47, “X02, “X02, °X40,°X20, 
“X47, “X03, “X02, “X40, “X20, 
“X47 ,~X04, “X02, “X40, X20, 


“X00, “X00, “X00, “XOC 
*X00000003 
UDAY 
UMONTH 
UYEAR 
*X00000001 
SHIPS+68 
*x00000002 
*X00000002 
SHIPS 
*X00000001 
SHIPS 
*X00000002 
*X00000001 
‘SHIPS 
*X00000001 
SUMREP+68 
*X00000002 
*X00000002 
SUMREP 
*X00000001 
SUMREP 
*X00000002 
*X00000001 
SUMREP 


28-Jun-1986 15:58:45 VAX RPG II V2.1 


28-Jun-1986 15:56:12 RPG$: [HEBERT .RPG] SHIPS .R 
“X50 ; 
“X91 ,°X03,“X91,°X44, “X2F , “X92, X44, “X2F , “X92, “X00 : 
“X92, ~X00 ; 
“X93, “X00 ; 


“X91, “X44, “X2C, “X92, “X03, “X91, “X00 : 


Page 2 


PG;1 (1) 
> "SHIPS" 


"SUMREP" 
"G..@ ...D/.D/.." 
"G..@ .." 
"G..@.." 

"G..@ .D,....9 


G—-p Suns saidwo @ Bunasdsayuy 


’ 000000A0 


O00000B0 
O00000B8 
000000C4 
000000D4 


OOOOOOEC 
O0O0000FO 
OOOOOOF4 
OOOOO0F8 
00000108 


00000002 


00000010 
00000013 
Q000001A 
00000021 
00000028 


00000539 
00000541 
00000544 
00000548 
0000054A 
0000054A 
00000544 


'0000054D 


+ 


-BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
. BYTE 
- LONG 
. LONG 


“X50, “X52, “X4F , “X44, “X55, “X43, “X54, “X20, “X53, “X48, “X49, “X50, “X4D, “X45, “X4E, “X64 ; 


“X20, “X52, “X45, “X50, “X4F, “X52, “X54 
“X53, “X48, “X49, “X50, “X4D,.°X45, “X4E, “X54, “X53 
“X44 ,°X49, “X56, “X49, “X53, “X49, “X4F, “X4E, “X20, “X20, “X44, “X45, “X50, “X54 


“X51, °X31,°X20, “X20, “X51, “X32, “X20, “X20, “X51, “X33, “X20, “X20, “X51, “X34, “X20, “X20 ; 


“X54, °X4F , “X54, °X41, “X4C 
*X00000002 
*X00000003 


.ADDRESS SHIPS 


. BYTE 
._ BYTE 
. PSECT 
. ENTRY 
MOVAB 
MOVAB 
SUBL2 


.MOVAB 


MOVAB 
MOVAB 
MOVAB 


“X3C, “X3D, “X3D, “X20, “X54, “X6F , “X74, “X61, “X6C, “X20, “X66, “X6F , “X72 


“X3C,“X3D, “X3D, “X20, “X47, “X52, “X41, “X4E, “X44, “X20, “X54, “X4F, “X54, “X41, “X4C ; 


$CODE 

SHIPS, “XOFFC 
G*RPG$HANDLER, (FP) 
$LOCAL+*X26, -(SP) 
#°X0C, SP 
$LOCAL+7X80, R11 
$PDATA+~X80, R10 
G*RPG$IOEXCEPTION, R9 
G*RPG$PRINT, R8 


Program epilogue code 


72$: 
733: 


CALLG 
BLBS 
CALLG 
BRB 


MOVL 
RET 


$PDATA+“X8C(R10), G*RPG$TERM_PRINT 
RO, 72$ 
$SPDATA+~X94(R10), G°RPG$IOEXCEPTION(R9) 


73$ 


#°X01, RO 


"PRODUCT SHIPMENT" 
"" REPORT" 
"SHIPMENTS" 
"DIVISION DEPT: 
"Q1 Q2 Q3 Q4 
"TOTAL" 


"<== Total for" 
"<== GRAND TOTAL" 





(Continued on next page) 
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Figure 4-1 (Cont.): 


SHIPS 


Cross Reference in Alphabetical Order ® 


DEPQTY 
DEPT 
DIV 
DIVQTY 
FINQTY 
PROD 
PROQTY 
QTY 
SHIPS 
SUMREP 
UDATE 


SHIPS 


19# 
14% 
13# 
21% 
23# 
15# 
18# 


. 10% 


8# 
OF 
28 


Indicator Cross Reference 


SHIPS 
Compilation Summary 


PROGRAM SECTIONS 


Name @ 
0 $CODE 
1 $LOCAL 
2 $PDATA 
3 RPG$UDATE 
4 RPG$HALTS 


19 21 22 


38 

37 44 46 
21 23 48 
23 52 

39 

19 41 

16 18 40 
12 

i1 25 


18 19 36 
23 37 43 


27 30 32 


® Bytes 
1358 
1280 
279 

6 

9 


50 


42 


Attributes ® 


PIC 
PIC 
PIC 
PIC 
PIC 


Sample Compiler Listing 


28-Jun-1986 15:58:45 VAX RPG IT V2.1 Page 11 
28-Jun-1986 15:56:12 RPG$: [HEBERT .RPG]SHIPS.RPG;1 (1) 


28-Jun-1986 15 
28-Jun-1986 15:56:12 RPG$: [HEBERT .RPG]SHIPS.RPG;1 (1) 


47 


28-Jun-1986 15 
.28-Jun-1986 15 


CON 
CON 
CON 
OVR 
OVR 


LCL 
LCL 
LCL 
GBL 
GBL 


7:58:45 VAX RPG II V2.1 Page 12 


7:68:45 VAX RPG II V2.1 Page 13 
7:66:12 RPG$: [HEBERT .RPG]SHIPS.RPG;1 (1) 


SHR EXE RD NOWRT Align(2) 
NOSHR NOEXE RD WRT Align(2) 
SHR NOEXE RD NOWRT Align(2) 
NOSHR NOEXE RD WRT Align(2) 
NOSHR NOEXE RD _ WRT Align(2) 
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COMMAND QUALIFIERS © 





RPG /LIST/MACHINE_CODE/CROSS_REFERENCE/CHECK=ALL/DEBUG/OBJECT/SEQUENCE_CHECK/WARNINGS=ALL SHIPS.RPG 
/CROSS_REFERENCE /MACHINE_CODE /SEQUENCE_CHECK 

/CHECK= (RECURSION , BOUNDS., BLANKS_IN_NUMERICS) 

/DEBUG=(SYMBOLS., TRACEBACK) 

- /WARNINGS= (OTHER , INFORMATION) 


STATISTICS 

Run Time: 5.26 seconds 
Elapsed Time: 6.58. seconds 
® Page Faults: 270 
@® Dynamic. Memory:. 348 . pages 
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Key to Figure 4-1: 


900080 


oo 


e e689 


e 


The program name. 

The date and time of compilation. 

The name and version number of the compiler. 

The creation date and time of the source file. 

The complete file specification (device:[directory]filename.type;version) 
for the source file. The number in parentheses is a text editor page 
number. 

Items 1 through 5 appear at the top of each page in the listing file. 
The 80-column ruler. . 

Source line numbers assigned by the compiler. The VAX/VMS 
Debugger uses these line numbers as location specifications. 

The letter C after the line number indicates that the line was generated 
by a copy directive. 

Source Listing—source code. 


Machine Code Listing—the compiler-generated object code for the 
program you compiled. 


Cross-Reference in Alphabetical Order—the user-defined names in 
alphabetical order and the line numbers on which they are referenced. 
The first column with the pound sign (#) after the number lists the 
line number where the data name is defined. For example, DEPQTY 
is defined on line 19 and referenced on lines 19, 21, and 22. 


DEPQTY 19# 19 21 22 


Indicator Cross-Reference—the indicators and the line numbers on 
which they are referenced. For example, indicator 01 is referenced on 
lines 12, 18, 19, and 36. 


O1 12 18 19 36 


PROGRAM SECTIONS—names the PSECT numbers and names. 
The bytes allocated for each PSECT. 


The PSECT attributes. See the VAX/VMS Linker Reference Manual for 
information on PSECT attributes. 


COMMAND QUALIFIERS—lists the command line you entered and 
names the compiler defaults that were in effect when the program was 
compiled. 


The CPU time used to ‘compile the program. 


Interpreting a Compiler Listing 


@® The time elapsed to compile the program. 
® The number of page faults. 
® The number of virtual memory pages used to compile the program. 
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Chapter 5 


Debugging Programs 


The VAX/VMS Debugger enables you to debug VAX RPG II programs 
by monitoring the flow of program execution and logic. For a complete 
description of debugger capabilities, see the VAX/VMS Debugger Reference 
Manual. 


The debugger lets you do the following: 


Set breakpoints to stop program execution just before a specified line 
is executed. 


Set tracepoints to cause the debugger to pause and display a message 
whenever a specified line is executed. 


Set watchpoints to cause the debugger to stop and display a message 
whenever a specified variable is modified. 


Examine and modify source code. 
Examine and modify data. 
Evaluate arithmetic expressions. 


Step through a program—single STEP commands cause the debugger 
to execute one or more lines and then stop program execution. 


The debugger needs information generated by both the VAX RPG II com- 
piler and the VAX/VMS Linker. Specifying the /DEBUG qualifier with 
the RPG command creates the symbolic information for the debugger. 
Specifying the /DEBUG qualifier with the LINK command makes the 
information available to the debugger. 
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At compile time, VAX RPG II supports the following options for the 
/DEBUG=options qualifier: 


e ALL 
° NONE 

e [NOJTRACEBACK 
e [NO]SYMBOLS 


Specifying the /DEBUG=SYMBOLS qualifier for the RPG command allows 
you to examine and change the contents of variables throughout your 
program. However, file names from File Description specifications are not 
available as variables. 


If you omit the /DEBUG qualifier from the RPG and LINK commands, 
you can specify the /DEBUG qualifier with the RUN command. In this 
case, no symbolic information is available to the debugger; you must make 
every reference to a program variable in terms of its absolute address. 


If you do not specify the /DEBUG qualifier with any of the RPG, LINK, 
or RUN commands and an error occurs, you receive a traceback list 

(a description of the logic flow up to the point where the error was 
detected). However, you cannot invoke the debugger. If you compile 
your program with the /DEBUG-NOTRACEBACK qualifier or link your 
program with the /NOTRACE qualifier, you do not receive the traceback 
list. The default options for the /DEBUG qualifier are TRACEBACK and 
NOSYMBOLS. 


If you want to use the source line display while using the COMPILE 
command, you must inform the debugger where the source file resides. 
To do this, complete the following steps: 


1. Define the symbol RPG to include symbols for the VAX/VMS 
Debugger. For example: 


$ RPG :== RPG/DEBUG. 
2. Execute the VAX RPG II editor COMPILE command during the editing 
session 


3. Execute the LINK/DEBUG command after exiting from the VAX RPG 
II editor 


4. Execute the RUN command 
5. Enter the debugger command: SET SOURCE source-file-spec 


See Chapter 3 for information on compiling and linking VAX RPG II 
programs and their respective command qualifiers. | 
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If you are using the VAX Performance and Coverage Analyzer (the 
Analyzer), you must specify the following: 


/DEBUG=SYS$LIBRARY : PCA$OBJ .OBJ MYPROGRAM.OBJ 


The VAX Performance and Coverage Analyzer consists of a collector and 
an analyzer. The collector gathers information (such as execution counts) 
on your program while it is executing. The analyzer makes it possible to 
interpret the data gathered by the collector. The analyzer is used to track 
a performance problem in an entire program down to a certain module, 
or even down to a certain line of code. See Appendix C for an example 
of the VAX Performance and Coverage Analyzer applied to a VAX RPG II 


program. 


9.1 Using the Debugger with VAX RPG Il 


Debugging VAX RPG II programs is somewhat different from debugging 
programs in other languages. The VAX RPG II program cycle determines 
the order in which the program lines are processed. See Chapter 1 for a 
complete discussion of the VAX RPG II program cycle. 


You can reference those line numbers VAX RPG II assigns to your program 
in the listing file. The line numbers you specify in columns 1 through 5 
of a specification are not used. The compiler assigns line numbers only to 
certain specifications at specific points in the logic cycle; therefore, you can 
specify a breakpoint or tracepoint at these points in the program: 


eA break at a File Description specification (see Chapter 15 for more 
information on specifications) occurs just before an input or update file 
is opened or just before an output file is created. The line number of 
this break corresponds to the File Description specification for this file. 


e A break at an Input specification occurs before the fields are loaded 
with data from a record. The line number of this break corresponds to 
the record definition in an Input specification. 


¢ You can set two breaks for each Calculation specification. The first 
break occurs just after testing control-level indicators, if used, and just 
before testing conditioning indicators. The second break occurs just 
before executing the operation code. For example, if a Calculation 
specification begins with line number 25, you can specify the line and 
statement number SET BREAK 25.1 to test indicators. 
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SET BREAK 25.2 breaks just before executing the operation code. If a 
particular Calculation specification has no indicators, SET BREAK 25 
breaks just before executing the operation code. 


e A break at an Output specification occurs after the output buffer has 
been built but before the record is output. The line number of the 
break corresponds to the record definition in an Output specification. 


5.2 Debugger Commands and Keywords 


There are many debugger commands, but not all are appropriate for 
use in debugging VAX RPG II programs. Table 5-1 lists some debugger 
commands and keywords (and their abbreviations) that are helpful in 
debugging VAX RPG II programs. 


Table 5-1: Debugger Commands and Keywords 


Command 
Names (abbrev) Keywords (abbrev) 
SET (SE) LANGUAGE (LA) 
SHOW (SH) MODULE (MODU) 
CANCEL (CAN) SCOPE (SC) 
EXAMINE (E) BREAK (B) 
EVALUATE (EV) TRACE (T) 
DEPOSIT (D) WATCH (W) 
EXIT (EX!) 
STEP (S) 
GO (G) 

- EDIT (ED) 


The rest of this chapter describes these debugger commands and explains 
how to use them. 
5.3 Preparing to Debug a Program 


This section describes the SET LANGUAGE and SHOW LANGUAGE 
commands used to create the proper environment for debugging a 
VAX RPG II program. 


5-4 Debugging Programs 


5.3.1 SET LANGUAGE Command 


The SET LANGUAGE command causes the debugger to conduct the 
debugging dialogue according to the conventions of the specified language. 
If your program does not call any subprograms written in languages other 
than RPG II, you do not need to use the SET LANGUAGE command. 

If your program calls a subprogram written in another language, you 

can cause the debugger to execute the subprogram by specifying the 
STEP/INTO command. See Section 5.4.5 for information about the 
/INTO qualifier. After the debugger has stepped into the subprogram, 
you must use the SET LANGUAGE command to specify the language of 
the subprogram. After you have finished executing the subprogram and 
you have returned to the main program, you must use the 

SET LANGUAGE command to specify the language of the main program. 


The format of the SET LANGUAGE command is as follows: 
SET LANGUAGE language 


language 
Specifies the language to be used. 


5.3.2 SHOW LANGUAGE Command 


To determine the language of the program currently being executed, use 
the SHOW LANGUAGE command. The format of the 
SHOW LANGUAGE command is as follows: 


SHOW LANGUAGE 


The debugger responds by displaying the program’s language, as shown 
in the following example: 


DBG>SHOW LANGUAGE 
language: RPG 
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5.4 Controlling Program Execution 


To see what is happening during execution of your program, you must be 
able to suspend and resume the program at specific points. The following 
commands are available for these purposes: 


SET BREAK 
SHOW BREAK 
CANCEL BREAK 
SET TRACE 
SHOW TRACE 
CANCEL TRACE 
SET WATCH 
SHOW WATCH 
CANCEL WATCH 
SHOW CALLS 
GO 

STEP 

TYPE 

CTRL/Y 

EXIT 


You can specify a VAX RPG II label as a breakpoint or a tracepoint. These 
labels correspond to specific points in the logic cycle. The following list 
describes VAX RPG II labels: 
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*DETL breaks just before outputting heading and detail lines. 


*GETIN breaks just before reading the next record from the primary 
or secondary file. 


*TOTC breaks just before performing total-time calculations. 
*TOTL breaks just before performing total-time output. 

*OFL breaks just before performing overflow output. 

*DETC breaks just before performing detail-time calculations. 


5.4.1 SET BREAK, SHOW BREAK, and CANCEL BREAK Commands 


The BREAK commands allow you to select specific locations for program 
suspension, so that you can examine or modify the following data: 


e Variables 

¢ Table entries 

e Array elements 

When you specify a table name, you can examine or modify the entry 
retrieved from the last LOKUP operation. 

You can also set a breakpoint at any point listed in Section 5.1. 

The BREAK commands perform the following functions: 

¢ SET BREAK defines the line number that will suspend execution. 

e SHOW BREAK displays all breakpoints currently set in the program. 
e CANCEL BREAK removes selected breakpoints. 


The format of the SET BREAK command is as follows: 


SET BREAK %LINE lin-num[.stmnt-num] [DO(command(s))] 


lin-num 
Specifies the line number where the breakpoint will occur. You can also 
specify a logic cycle label, a TAG name, or a subroutine label. 


stmnt-num 

Specifies the statement number where the breakpoint will occur. You 
can use statement numbers only with Calculation specifications that have 
conditioning indicators. 


DO(command(s)) 
Requests the debugger to perform the specified debugger commands, if 
specified, when the breakpoint is reached. 
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In the following example, SET BREAK examines variables TOTAL and 
AREA when the breakpoint at line 100 is reached: 


DBG>SET BREAK %LINE 100 DO(EXAMINE TOTAL; EXAMINE AREA) 
The format of the SHOW BREAK command is as follows: 
SHOW BREAK 


SHOW BREAK takes no arguments. The debugger responds by displaying 
the current breakpoints, as shown in the following example: 


DBG>SET BREAK LOOP 

DBG>SET BREAK %LINE 50 
DBG>SHOW BREAK 

breakpoint at ARRX37\LOOP 
breakpoint at ARRX37\%/LINE 50 


The format of the CANCEL BREAK command is as follows: 
CANCEL BREAK Y%LINE lin-num[.stmnt-nun] 
/ALL 


lin-num[.stmnt-num] 
Removes the breakpoint at the specified line and statement number, logic 
cycle label, TAG name, or subroutine label. 


/ALL 
Removes all breakpoints in the program. 


Normally, the debugger displays the line number when it suspends 
execution because of a breakpoint or step. There are two exceptions to 
this behavior: 


e When stepping through a subroutine, the debugger displays the 
subroutine label. . 


DBG>STEP 
stepped to PROG1\SUB1 


e¢ When stepping through a TAG, the debugger displays the TAG name. 


DBG> STEP 
stepped to PROG1\TAG1 
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5.4.2 SET TRACE, SHOW TRACE, and CANCEL TRACE Commands 


The TRACE commands let you set, examine, and remove tracepoints in 
your program. A tracepoint is similar to a breakpoint in that it suspends 
program execution; however, after displaying the trace variables, program 
execution resumes immediately. Thus, tracepoints let you follow the 
sequence of program execution to ensure that execution is occurring in the 
proper order. 


Tracepoints and breakpoints are mutually exclusive. If you set a tracepoint 
at a current breakpoint, the breakpoint will be canceled. If you set a 
breakpoint at a current tracepoint, the tracepoint will be canceled. 


The TRACE commands perform the following functions: 
¢ SET TRACE establishes points within the program where execution is 
momentarily suspended. 


¢ SHOW TRACE displays the points in the program where tracepoints 
are currently set. 


e¢ CANCEL TRACE removes one or more tracepoints currently set in the 
program. 


The format of the SET TRACE command is as follows: 


SET TRACE %LINE lin-nun[.stmnt-nun] 


lin-num[.stmnt-num] 
Specifies the line and statement number, logic cycle label, TAG name, or 
subroutine label where the tracepoint will occur. 


The format of the SHOW TRACE command is as follows: 
SHOW TRACE 


SHOW TRACE takes no arguments. The debugger responds by displaying 
the current tracepoints, as shown in the following example: 


DBG> SET TRACE LOOP2 

DBG> SET TRACE %LINE 100 

DBG> SHOW TRACE 

tracepoint at ARRX37\LOOP2 
tracepoint at ARRX37\%LINE 100 
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The format of the CANCEL TRACE command is as follows: 


CANCEL TRACE Y¥%LINE lin-num[.stmnt-nun] 
/ALL 


lin-num[.stmnt-num] 
Removes the tracepoint at the specified line and statement number, logic 
cycle label, TAG name, or subroutine label. 


/ALL 
Removes all tracepoints in the program. 


5.4.3 SET WATCH, SHOW WATCH, and CANCEL WATCH Commands 


The WATCH commands let you monitor the contents of variables. 
Watchpoints determine when an attempt is made to modify variables. 
When an attempt is made, the debugger halts program execution and 
prompts for a debugger command. Watchpoints are monitored contin- 
ually. Thus, you can determine whether a particular variable is being 
modified inadvertently during program execution. Watchpoints, trace- 
points, and breakpoints are mutually exclusive. The WATCH commands 
perform the following functions: 


e SET WATCH defines the variables to be monitored. 

e SHOW WATCH displays the variable currently being monitored. 
¢ CANCEL WATCH disables monitoring of specified variables. 
The format of the SET WATCH command is as follows: 


SET WATCH vbl 


vbl 
Specifies the variable to be monitored. You can monitor variables and 
array elements. 


5-10 Debugging Programs 


In the following example, SET WATCH sets a watchpoint for the variable 
AREA: 


DBG>SET WATCH AREA 
The format of the SHOW WATCH command is as follows: 
SHOW WATCH 


SHOW WATCH takes no arguments. The debugger responds by display- 
ing the current watchpoints, as shown in the following example: 


DBG>SET WATCH INDEX2 
DBG>SHOW WATCH 
watchpoint of ARRX37\INDEX2 
The format of the CANCEL WATCH command is as follows: 
CANCEL WATCH vb1/ALL 
vbi | 
Specifies the variable that disables monitoring. 
/ALL 
Removes all watchpoints from the program. 
The following command cancels the watchpoint for the variable AREA: 


DBG>CANCEL WATCH AREA 


5.4.4 SHOW CALLS Command 


The SHOW CALLS command can be used to produce a traceback of calls 
to program modules. It is particularly useful when you have returned to 
the debugger following a CTRL/Y command. The format of the SHOW 
CALLS command is as follows: 


SHOW CALLS [n] 


The debugger displays a traceback list, showing the sequence of calls to 
program modules leading to the current module. 


If you include a value for n, the n most recent calls are displayed. 
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5.4.5 GO and STEP Commands 


The GO and STEP commands let you initiate and resume program execu- 
tion. The GO command initiates execution from the current line or at a 
specified point in the program and continues to the end of the program or 
to the next breakpoint. The STEP command initiates execution from the 
current line, and continues for a specified number of lines. 


The format of the GO command is as follows: 


GO (%LINE lin-nun[.stmnt-nun)] 


lin-num[.stmnt-num] 
Specifies the line and statement number, TAG name, or subroutine label 
where execution will begin. 


The normal use of the GO command is to continue execution after a 
breakpoint or at program initiation. Resuming execution at a point other 
than the current line can cause unpredictable results because of the nature 
of the VAX RPG II logic cycle. 


Use the STEP command to execute one or more VAX RPG II program 
lines and immediately return to the debugger. The format of the STEP 
command is as follows: 


STEP [/qualifiers] [n] 


The value specified for n determines the number of statements to be 
executed. If you specify 0, or omit a value for n, a value of 1 is assumed. 


You can specify the following qualifiers with the STEP command: 


/[NO]JSYSTEM 
Causes the debugger to count steps wherever they occur. The 
/NOSYSTEM qualifier is the default. 


/(NOJOVER 

Causes the debugger to ignore calls to subprograms as it steps through 
the program. That is, it steps over each call to a subprogram. The /OVER 
qualifier is the default. 
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/(NOJINTO 

Causes the debugger to recognize calls to subprograms as it steps through 
the program. That is, it steps into each subprogram. The /NOINTO 
qualifier is the default. | 


/(NOJLINE 
Causes the debugger to step through the program on a line by line basis. 
The /LINE qualifier is the default. 


/[NOJSOURCE 

Causes the debugger to display the lines of source code that corresponds 
to the lines being executed with each step. Source lines are also displayed 
when a breakpoint or watchpoint occurs. When stepping through Input 
and Output specifications, the debugger displays the first line of a record 
definition. The /SOURCE qualifier is the default. 


You can specify one or more qualifiers each time you issue a STEP 
command, or you can use a SET STEP command to override the defaults. 


The following command specifies that the defaults for the /LINE, /INTO, 
and /SYSTEM qualifiers are overridden: 


DBG>SET STEP NOLINE, INTO,SYSTEM 


When you subsequently issue a STEP command with no qualifiers, the 
debugger assumes these qualifiers (/NOLINE, /INTO, and /SYSTEM) are 
in effect. You can, however, supersede the current qualifiers by including 
a qualifier with a STEP command. 


The following command executes 10 lines, regardless of the SET STEP 
command: 


DBG>STEP/LINE 10 


It is advisable to use STEP to execute only one or a few lines at a time. 
To execute many lines and then stop, use a SET BREAK command to set a 
breakpoint, then issue a;GO command. 


5.4.6 TYPE Command 


The TYPE command displays the line of source code you specify. The 
format of the TYPE command is as follows: 


TYPE ({lin-num[:lin-nun] [,...]] 
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lin-num[:lin-num] | 
Specifies the lines of source code to be displayed. 


The following command displays lines 1 through 30: 
DBG>TYPE 1:30 

The following command displays lines 1 and 30: 
DBG>TYPE 1,30 


You can display the line after the current line by typing TYPE and by 
pressing the RETURN key. 


5.4.7 EDIT Command 


The EDIT command allows you to edit the file you are debugging. 
The editing session begins at the current debugging line. 


EDIT/EXIT specifies that you want to end the debugging session and 
begin an editing session. 


EDIT/NOEXIT specifies that you want to return to the debugging session 
after you make your edits. The /NOEXIT qualifier is the default. 


5.4.8 CTRL/Y Command 


You can use the CTRL/Y command at any time to return to the system 
command level. You issue this command when you press the CTRL 

key and the Y key at the same time. The dollar sign ($) prompt will be 
displayed on the screen. To return to the debugger, type DEBUG. Use the 
CTRL/Y command if your program goes into an infinite loop or, for some 
reason, fails to stop at a breakpoint. To find out where you were when 
CTRL/Y was executed, use the SHOW CALLS command after you have 
returned to the debugger. 
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5.4.9 EXIT Command 


The EXIT command lets you exit from the debugger when you are ready 
to terminate a debugging session. The format of the EXIT command is as 
follows: 


EXIT 


The EXIT command uses no arguments. To return to system command 
level after your program has terminated, use the EXIT command. 


5.5 Examining and Modifying Locations 


After you have set breakpoints and begun execution, the next step is 

to see whether correct values are being generated and, if necessary, to 
change the contents of variables as execution proceeds. You may also 
want to calculate the value of an expression that appears in your program. 
The debugger provides the following commands for these purposes: 
EXAMINE, DEPOSIT, and EVALUATE. 


5.5.1 EXAMINE Command 


The EXAMINE command lets you look at the contents of the following: 
e A variable 
e The current table entry 
e An array element 
e The I/O buffer 
The format of the EXAMINE command is as follows: 
EXAMINE vbl [,vbl] 
vbl 
Specifies a simple or subscripted variable. 
The following command displays the contents of the variable SALES: 


DBG> EXAMINE SALES 
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The following command displays the contents of the ninth element in 
array ARRAY: 


DBG>EXAMINE ARRAY (9) 


The following command displays the contents of the first through the 
tenth elements of the array ARRAY: 


DBG>EXAMINE ARRAY(1:10) 


You can examine indicators to see whether they are set on or off. Precede 
the indicator you want to examine with the string *IN. If an indicator is 
set on, 1 is displayed. If an indicator is set off, 0 is displayed. 


The following command displays the current setting for indicator 56: 
DBG>EXAMINE *IN56 

The debugger responds by displaying: 

+*IN56: "0" 


You cannot examine external indicators in this way, but you can do the 
following. To determine the current value of U5, for example, enter this 
command: 


DBG>CALL RPG$EXT_INDS(5) 
The debugger responds by displaying: 
value returned is 0 


The program must have been linked with the /NOSYSSHARE qualifier to 
do this. 


You can also display the current contents of the I/O buffer. To display 
the I/O buffer, specify the name of the input file, update file, or output 
file, a dollar sign ($), and the string BUF. 


The following command displays the contents of the I/O buffer for the 
input file INPUT: 


DBG>EXAMINE INPUT$BUF 


The following command displays the ASCII equivalent of the string 
STRING, which is n characters in length: 


DBG>EXAMINE/ASCII:n STRING 


To examine a variable which contains the at sign (@), use % NAME as 
follows: 


DBG>EXAMINE %NAME 'ITEMG' 
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5.5.2 DEPOSIT Command 
The DEPOSIT command lets you change the contents of specified vari- 
ables. The format of the DEPOSIT command is as follows: 
DEPOSIT vbl=value 


vbl 
Specifies the variable that the value is deposited into. 


value 
Specifies the value to be deposited. 


You can change the contents of a specific variable or of several consecutive 
variables, as shown in the examples in this section. 


Values deposited into numeric fields are aligned on the decimal point. 
Shorter fields are padded with zeros to the left and right of the decimal 
point. 


The following command places the decimal value 100 into the variable 
BONUS: 


DBG> DEPOSIT BONUS=100 


The following command places the decimal values 100, 150, and 200 into 
elements 1, 2, and 3 of array ARRAY: 


DBG> DEPOSIT ARRAY(1)=100, 150, 200 


The delimiters used to enclose ASCII strings in the DEPOSIT command 
can be either single (') or double (") quotation marks. Use the keyboard 
apostrophe for the single quotation mark. 


Values deposited into character fields are left justified. If the value con- 
tains fewer characters than the character field, the field is padded on the 
right with spaces. 


The following command places the string ACTIVE in the variable STATUS: 
DBG> DEPOSIT STATUS="ACTIVE" 


You can also use DEPOSIT to set indicators on or off. Precede the indica- 
tor you want to set with the string *IN. To set an indicator on, specify 1 as 
the variable value. To set an indicator off, specify 0 as the variable value. 


The following command sets indicator 56 on: 


DBG> DEPOSIT *IN56 = "1" 
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5.5.3 EVALUATE Command 


The EVALUATE command lets you use the debugger as a calculator 
to determine the value of arithmetic expressions. The format of the 
EVALUATE command is as follows: 


EVALUATE expression 
expression 
Specifies the expression whose value is to be determined. 


The following command displays the value of the expression 
ARRAY(FLD1) * FLD2: 


DBG>EVALUATE ARRAY(FLD1) * FLD2 
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Using VAX RPG II Features on VMS 


This part of the manual provides information on the use 
of VAX/VMS features in the development of VAX FPG Il 
programs: 


Screen handling 

— Workstation (WORKSTN) files syntax 

— VAX FPG II interface with VAX Forms Management 
System (VAX FMS) 

— Screen and display forms conversion utility 

Indicators 

Files 

Printer output files 

Tables 

Arrays | 

System routines and system services 

Program optimizing 


Chapter 6 


VAX RPG II Screen Handling 


VAX RPG II screen handling is accomplished in two ways: (1) language 
syntax in the VAX RPG II program, and (2) various screen design ac- 
tivities outside of the VAX RPG II program, including the VAX Forms 
Management System (VAX FMS). 


The general language syntax is based on WORKSTN files used in other 
vendor RPG II implementations which allow RPG II programs to 
interact with a terminal. In these implementations, a WORKSTN file 
interacts with forms that are defined externally to the RPG program. 


The VAX RPG II language provides an interface between WORKSTN 
files and VAX FMS forms. You can create and modify these forms with 
an interactive forms editor. If you are developing new applications, you 
should refer to the FMS/EDIT chapter of the VAX FMS Utilities Reference 
Manual. If you are working with existing WORKSTN file programs and 
forms based on Screen and Display (S and D) specifications, VAX RPG 

II provides a Conversion Utility that converts the Screen and Display 
specifications to the VAX FMS form language. You can use the forms on 
VT100 and VT200 terminals. Additional information on VAX FMS can be 
found in the VAX FMS Utilities Reference Manual. 


NOTE 


Use of the DSPLY operation code and WORKSTN files in the 
same program can produce undesirable run-time results on your 
terminal screen. Displayed information can become mixed and 
garbled, because neither screen handling mechanism is aware 
of the other and no coordination takes place. Concurrent use is 
highly discouraged. 
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6.1 Creating and Modifying Forms 


A VAX FMS form provides the communications bridge between a VAX 
RPG II program WORKSTN file and a terminal screen. VAX FMS forms 
include fields and constant information. You can specify various video 
attributes, such as blink or underline, for parts of the form. You can use 
fields in the form to display information from the program, or to input 
information that will be returned to the program. VAX FMS has various 
methods of validation for each input field. 


VAX FMS has two methods for creating forms: 


1. The VAX FMS Form Editor Utility allows you to interactively design 
the layout of a form, showing the position of each field as well as 
constant information. The form can be modified later. You invoke the 
VAX FMS Form Editor Utility with the following command: 


$ FMS/EDIT form-name! 


2. You can also create a form by editing a text file that contains the 
VAX FMS form language description for the form. After you cre- 
ate a text file, it can be translated to the VAX FMS binary form 
representation with the following command: 


$ FMS/TRANSLATE form-language-file 


Note that the output from either FMS/EDIT or FMS/TRANSLATE 
is the binary representation of a form with the default file type FRM. 
You can use the VAX FMS Form Editor Utility to modify the form 
after a form language file has been translated. The form language 
file can be edited again and retranslated. You can also get a file that 
has the form language from any VAX FMS form using the following 
command: 


‘ $ FMS/DESCRIPTION/FULL form-name 


1 For detailed information on VAX FMS and this command, refer to the VAX FMS Utilities Reference Manual. 
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6.2 Creating Form Libraries 


You place the forms used by your program in a VAX FMS form library. 
For example, an inventory program could have three forms: 


1. PART_NUMBER—to display a part number 
2. PART_DISPLAY—to display data about a part 


3. PART_ERROR—to display a message if a request was made for an 
invalid part. 


You would place these three forms in the PARTS form library as follows: 


$ FMS/LIBRARY/CREATE PARTS PART_NUMBER, PART_DISPLAY , PART_ERROR 


The VAX RPG II program would then be able to access the three forms in 
this library by referencing the indicated names. Note that other program- 
ming languages in the VAX/VMS language family can access these forms 
from the PARTS form library. 


6.3 WORKSTN Files 


WORKSTN files allow you to access many VAX FMS form capabilities 
from a VAX RPG II program. However, WORKSTN files provide only 

a subset of the capabilities available with VAX FMS. The most complete 
interface between VAX RPG II and VAX FMS is provided by the callable 
interface to VAX FMS. These features are accessed in VAX RPG II pro- 
grams by the CALL, PARMx!, EXTRN, and GIVNG operation codes. For 
additional information on these operation codes, see Chapters 12 and 16. 
In most cases, WORKSTN files will provide all the capabilities you need 
to access VAX FMS. You can use the CALL interface with WORKSTN 
files to access those VAX FMS features that are not supported directly 
by WORKSTN files. If you choose to use WORKSTN files and the CALL 
to VAX FMS in the same program, careful attention to Section 6.3.7 will 
ensure the best results. 


WORKSTN files are further described on Control, File Description, Input, 
Calculation, and Output specifications. 


1 PARMx includes PARM, PARMD, and PARMV. 
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6.3.1 Control Specifications (H) 


The H specification program name is used only as a second choice for 
the VAX FMS form library name, if an FMTS name is not supplied. See 
Section 6.3.2 for a detailed description. 


6.3.2 File Specifications (F) with WORKSTN Files 


WORKSTN files must include the letter C for the file type and WORKSTN 
for the file device. There can be only one WORKSTN file in a program. A 
WORKSTN file can have continuation lines that describe the form library 
name (FMTS), the INFDS data structure, and SLN variable. You indicate 
continuation lines for the File specification by inserting a K in column 53. 
The only fields available for use on a continuation line are columns 53 
through 65 (or 53 through 67, depending on the option). The following 
continuation-line option format is accepted by VAX RPG II. 


Column Contents 

53 K 

54-59 Option name 
60-65 /67 Value 


NOTE 


If the F specification is a WORKSTN file, it cannot specify a 
symbolic device. 


If you supply an FMTS name, then that name will be used for the 

VAX FMS form library name (such as PARTS in the preceding example). 
If you do not supply an FMTS name, the program name (in columns 75 
through 80 of the Control specification) is used for the VAX FMS form 
library name. If the program name is not supplied, the WORKSTN file 
name is used as the VAX FMS form library name. 


If you supply a start line (SLN) option, the SLN value will offset the form 
from the start line of the form. The offset form must fit on the screen, or 
an error status will occur at run time. See Section 6.5.1 for examples. 
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WORKSTN files must have a file designation of primary (P) or demand 
(D). If you choose P, all forms display and forms input will be performed 
at a specific point in the logic cycle. If you choose D, the EXCPT and 
READ operation codes can be used to determine when forms are displayed 
and when input from forms is performed. (Note that if you make the 
WORKSTN file the primary file, no secondary files are allowed in the 
program.) See Section 6.5.1 for further details. 


6.3.3 Input Specifications (I) 


VAX RPG II Input specifications are used to describe the declarations and 
processing to be performed when input is received from the WORKSTN 
file. The Input specifications extract data from record buffers and set any 
record identifying indicators on. 


You program the Input specifications similarly to an input or update 
file. The most important part of the Input specifications is ensuring that 
the start and end positions for each field match the field size and order 
that was specified in the form. You can help to set up the input field 
specifications correctly with the following command: 


$ FMS/DESCRIPTIONS/BRIEF form-name 


The output from this VAX FMS command isa list of the fields in the form, 
including the size of each field. If particular fields are display only, they 
are indicated as such. This information can help you select the proper 
starting and ending field positions for any input field specifications. Some 
input constants may cause the VAX FMS record buffer to be adjusted. If 
you are converting from Screen and Display specifications, see Section 6.7. 


6.3.4 Calculation Specifications (C) 


If you use a D file designation, making the WORKSTN file a demand (D) 
file, then you must use the EXCPT and READ operation codes to control 
both form display and form input. The EXCPT operation code works with 
a WORKSTN file similarly to any other file. EXCPT will cause output 
from all exception Output specifications with conditioning indicators set 
on. Note that you can use EXCPT with factor 2 for finer control over the 
specific Output specifications. : 


You use the READ operation code to get input from the last form dis- 
played (that had input fields) since your previous read. 
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To detect end-of-file (EOF) on the WORKSTN file, you can specify an 
indicator in columns 58 and 59 with the READ operation code. End-of-file 
is reached when a READ operation code is executed and the last group © 
of forms displayed since the previous read had no input fields. This read 
operation will cause the EOF indicator on the READ operation code to be 
set on, if present. Otherwise, your program terminates. 


The READ operation code can also have an indicator to detect errors. See 
Section 6.5 for further details. 


6.3.5 Primary WORKSTN File 


A primary WORKSTN file does not require any Calculation specification 
operation codes. However, form display and form input during the 

logic cycle are similar to an EXCPT operation code followed by a READ 
operation code. The LR indicator will be set on when a READ operation 
to the primary WORKSTN file is executed and the last form displayed has 
no input fields. 


Primary WORKSTN files are processed just like any other primary input 
file. However, input can become complicated, especially if this is the first 
time through the logic cycle. 


When the logic cycle starts, input to the WORKSTN file can come from 
one of two places. If no form has been displayed on the first cycle, then 
a blank record is generated in place’ of input from the WORKSTN file. 

If an input form has already been displayed because the first-page (1P) 
indicator is present ina WORKSTN Output specification, then input is 
obtained from the WORKSTN file. 


When it is not the first logic cycle, all input is assumed to be coming from 
the WORKSTN file. If no input form was displayed for this logic cycle, 
then end-of-file will be flagged and your program will terminate. 


In any requested READ operation code (for a demand WORKSTN file), a 
blank record will be returned until a form is output. 
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6.3.6 Output Specifications (0) 


Output specifications for WORKSTN files differ only slightly from Output 
specifications for other files. Insert a K in column 42 of an Output field 
specification, indicating that the literal that begins in column 45 on that 
Output specification is the name of a form to be displayed. The field 
output specifications that follow the form specification can be data that is 
to be displayed on the form. 


The input and output record buffers for each form have the same field 
layout, except for an input constant converted by the S and D Converter. 
See Section 6.7 for further details. 


You can use FMS/DESCRIPTIONS/BRIEF (as in Input specifications) to 
help you specify the ending positions for output fields that contain data to 
be displayed on a form. 


Note that logic cycle output of forms requires you to insert a D in column 
15 for each output record for the WORKSTN file that indicates detail 
output. Each output record corresponds to one form that can be dis- 
played. Insert an E in column 15 for a demand WORKSTN file, indicating 
exception output that will be controlled by EXCPT operation codes. 


To indicate end-of-file on the WORKSTN file, the last-record (LR) indi- 
cator can be set on, or a READ operation code can be executed on the 
WORKSTN file, if the forms displayed since the last READ operation had 
no input fields. For a primary WORKSTN file, the LR indicator will be 
set on. For a demand WORKSTN file, any indicator specified o ona READ 
operation code in columns 58 and 59 is set on. 


6.3.7 VAX FMS Call interface Run-Time Support 


VAX RPG II provides run-time support to interface WORKSTN files to 
VAX FMS. If you want to use the WORKSTN files and call => 

VAX FMS (FDV$) routines in the same program, you must understand 
the built-in WORKSTN run-time support as described in this section. The 
VAX RPG II sample program SYS$EXAMPLE:RPGFMS.RPG uses 

VAX FMS to demonstrate the combined use of WORKSTN file syntax 
and VAX FMS calls. Comments in that program have particularly helpful 
information on the FMS form ‘REGISTER’ that is manipulated with 

VAX FMS (FDV$) routines. Workspace and input/output must be con- 
trolled through calls to VAX FMS. See the VAX FMS documentation for 
detailed information on the VAX FMS call interface. 
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To use the sample program, enter the following commands: 


$ RPG SYS$EXAMPLES : RPGFMS 

$ LINK RPGFMS, SYS$LIBRARY : RPGSCR 

$ DEFINE FMS$EXAMPLES SYS$SYSROOT: [SYSHLP . EXAMPLES . FMS] 
$ DEFINE INP FMS$EXAMPLES : SAMP 

$ DEFINE SAMP FMS$EXAMPLES : SAMP 

$ RUN RPGFMS 


The VAX RPG II WORKSTN run-time support provides an interface for 
performing four functions: 


e Initialization 

e Display a form 

e Read from a form 
e Termination 


Any error returned by a VAX FMS call will cause the program to halt, 
except as described in the following sections. 


6.3.7.1 Initialization 


During initialization, the run-time support attaches the terminal to 
FDV$ATERM using VAX FMS logical channel 255. Then, each form 
that you reference on the Output specifications is loaded into a separate 
workspace. Even if the same form name is given in different Output 
specification records, a separate workspace is created for each Output 
specification form reference. The form library is opened (on VAX FMS 
logical channel 254) only if loading a form fails. Thus, some or all of 
the forms can be linked into the program, and VAX FMS accesses the 
disk library only if necessary. Also during initialization, VAX RPG II 
loads RPG-specific named data for handling input constants and selective 
enabling and disabling of VAX FMS terminators. 


6.3.7.2 Displaying a Form 


Any program request to display a form (EXCPT operation code or logic 
cycle output) causes the run-time support to switch to the appropriate 
workspace, use FDV$PUTAL to output data from the WORKSTN file 
record buffer, and then use FDV$DISPW to display the loaded form. The 
run-time support keeps a list of all forms displayed since the previous 
program request to read from a form. Note that if the FDV$PUTAL 
returns the FDV$_NOF error, this error will be ignored. 
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6.3.7.3. Reading from a Form 


Any program request to read from a form (READ operation code or logic 
cycle input) will cause the run-time support to attempt to use FDV$GETAL 
on the form in the current workspace. If FDV$GETAL fails because the 
form in the current workspace has no input fields, the current workspace 
will be switched to the form displayed just prior to the last form. The 
specific errors which cause FDV$GETAL to try another form are 
FDV$_NOF and FDV$_DSP. The FDV$_UNF error is ignored. 
FDV$GETAL is then tried again. This process repeats until the 
FDV$GETAL succeeds, or until there are no more forms in the list. If 

the list is exhausted, the LR indicator will be set on in the program (this 
is because no input-capable forms have been displayed since the last 
READ operation). One special case is a READ operation before any out- 
put has occurred. In this case, a blank record will be returned. After the 
FDV$GETAL completes, all forms displayed since the last READ opetation 
are marked with FDOV$NDISP. 


If you wish to be able to read from a form, it must be either the last 
form displayed prior to the READ operation, or one of the first 100 forms 
displayed since the last READ operation. 


6.3.7.4 Termination 


During termination, all workspaces and the terminal are detached. If a 
VAX FMS form library is open, it is closed. 


6.3.7.5 Current Workspace 


VAX FMS maintains a current workspace. Therefore, you should be 
careful when you use VAX FMS calls that modify the current workspace. 
If you process forms that are not handled by the WORKSTN file, you will 
not be able to issue a READ operation to the WORKSTN file until you 
have displayed another form using WORKSTN file output. The output 
will properly reestablish the current workspace as corresponding to the 
form displayed with WORKSTN file output. 
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6.4 Command Keys (K Indicators) and Function Keys 


Command keys provide a way for you to interact with the program. When 
a form is displayed on a screen and the operator is entering input values, 
there are a number of ways to indicate that the form is complete. 


The most common method is to press either the RETURN key or the 
ENTER key. VAX FMS recognizes these keys as form terminators; when 
they are received, no further input is allowed to the current form and 
control returns to the program. The input operation that requested form 
input is considered to have concluded successfully. 


Command keys provide an alternative method to interact with a 

VAX RPG II program. In addition to the effects just described, one of the 
K indicators is set on while the others are set off. These input operations 
are also considered successful. Data from the form is read by the program; 
the status field in the INFDS indicates that a command key was entered. 
One of the typical uses for this feature is to provide a way for you to 
indicate which form to process next. The program can use the K indicators 
to condition further processing. 


All other form terminators are considered to be function keys. Any of 
these terminate input to the form and control returns to the program with 
normal status. Data from the form is read by the program; the status 
field in the INFDS indicates that a function key was entered; no error 
processing is initiated. In this case, all the K indicators are set off. 


In addition to providing a default definition of key sequences associated 
with command keys, VAX RPG II also allows you to specify a different set 
of command keys at run time. 


When a form is displayed, you may terminate the form by pressing the 
PF1 key followed by one of 36 characters. Other terminators act as 
function keys. 
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6.4.1 K Indicators 


VAX RPG II provides 36 K indicators: KA through KZ and KO through K9. 
These can be used as general-purpose indicators. In a program containing 
a WORKSTN file, their values can be modified at the following times: 


e If the WORKSTN file is a primary file, K indicators can change during 
normal logic cycle processing of the primary input file. 

e If the WORKSTN file is a demand file, K indicators can change as part © 
of the processing for a READ operation code on the WORKSTN file. 


In both cases, the indicators do not change if an error was encountered 
during the input operation. If there was no error, then all K indicators are 
set off and the K indicator corresponding to the command key entered is 
set on. 


6.4.2 Command Keys 
VAX RPG II provides 36 command keys. Each command key is associated 


with one K indicator. The default K indicator command key equivalence is 
described by the following table. 


Command Key KIndicator = 
<digit> K <digit> 


The <letter> is an uppercase letter. VAX FMS considers PF1/A or 
PF1/a to be different terminators. There is no provision for having two 
different VAX FMS terminators set on the same K indicator. 


6.4.3 Function Keys 


All form terminators except the ENTER and RETURN keys and the 
command keys are considered to be function keys. 
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6.4.4 User-Defined Command Keys 


Terminating a form by pressing the PF1A key will result in the KA 
indicator being set on. The default command keys definitions are given in 
Section 6.4.2. If you prefer another set of keys to be associated with the K 
indicators, you can enter a command like the following: 


$ DEFINE RPG$COMMAND_KEYS "305,306,307" 


The logical name is translated at run time and should consist of a list of 
numeric values separated by commas. Each entry is the 

VAX FMS-defined key sequence that identifies the key or sequence of 
keys that the operator must enter. The position within the list identifies 
the associated K indicator. The indicators have the following order: KA 
through KZ and KO through K9. The preceding example indicates that the 
sequence PF1/1 would set on the KA indicator, PF1/2 would set on the 
KB indicator, and PF1/3 would set on the KC indicator. 


You can redefine some or all of the default definitions. A default defi- 
nition will not be changed if the corresponding entry in the list has no 
value. A command key will not be associated with a K indicator if the 
corresponding entry is -1. 


Thus, this DCL command line has the meaning described in the following 
table. 


$ DEFINE RPG$COMMAND_KEYS "305, ,-1,307" 


Parameter Keys Indicator Explanation 

null {PF1] KB No change to default definition 
-1 KC No keys are associated with KC 
307 [3] KD Redefines default definition 


The other keys would retain their default definitions. 


Refer to the VAX FMS Form Driver Reference Manual for the VAX FMS 
key codes. To use the keypad keys as terminators, your keypad must 
be in application mode. You can do this by entering the following DCL 
command: 


$ SET TERMINAL/APPLICATION_KEYPAD 


Or, you can include a call to FDV$SPADA in the Calculation specifications 
(see the VAX VMS Form Driver Reference Manual). 
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6.4.5 Selective Enabling of Command Keys 


VAX RPG II enables all command keys and all function keys. Thus, if the 
program is trying to read from a WORKSTN file and you enter one of the 
key sequences that VAX FMS recognizes as a terminator, input to the form 
will be terminated and control will return to the program. 


Pressing the RETURN key or the ENTER key automatically terminates 
form input, but you can control the treatment of other keys. 


You can enable a list of terminators. Entering one of these keys terminates 
form input. Entering any other terminator does not end form input. VAX 
FMS instead signals an error and the key is ignored. 


As an alternative, you can disable a list of terminators. Entering one 
of these keys causes VAX FMS to signal an error and ignore the key. 
Entering any other terminator causes form input to be terminated. 


To use selective enabling, follow these steps: 
1. Define a function key User Action Routine (UAR) for each form with 
input fields. 


2. Define the named data item RPG$ENABLE_KEYS or 
RPG$DISABLE_KEYS for each form with input fields. 


3. Generate an object file that contains UAR information. 
4. Link this object file with your VAX RPG II program. 


Note that you can specify the same or different terminators for each form. 


6.4.5.1. Defining a Function Key UAR 


VAX RPG II provides the run-time routine needed to define a UAR as part 
of its VAX/VMS Run-Time Library support. You need to modify the form 
definition so that the VAX FMS Form Driver will invoke this routine when 
you enter a terminator. 


If you are using the VAX FMS Form Editor Utility, invoke the Editor 
Utility with the following command: 


$ FMS/EDIT form_library_name/FORM_NAME=formname 


In the FORM phase (assign form attributes), specify that you want a 
UAR for this form, then enter RPG$FUN—KEY_UAR in the field labeled 
Function Key UAR Name. 
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If you are using the VAX FMS Translate Utility, describe the UAR by 
adding the following command to the form definition: 


FUNCTION_KEY_ACTION_ROUTINE = 'RPG$FUN_KEY_UAR' 


6.4.5.2 Defining a Named Data Item 
If you are using the VAX FMS Form Editor Utility, you must first invoke 
the Editor Utility. Then, in the DATA phase (Enter Named Data Items), 
enter RPGSENABLE_KEYS or RPG$DISABLE_KEYS on the first (Name) 
line of a named data item, and a list of terminators (separated by commas) 
that are to be enabled or disabled. (If you enter both the 
RPG$ENABLE_KEYS and RPG$DISABLE_KEYS items for the same 
form, the disable entry will be ignored.) Terminator values are the same 
as those described in Section 6.4.4. For example, to enable PF1/A only, 
you would define a named data item with the name RPGSENABLE_KEYS 
and a value of 321. 


If you are using the VAX FMS Translate Utility, describe the named data 
item by adding a named data clause of the form: 


NAMED_DATA INDEX = n NAME = 'RPG$ENABLE_KEYS' DATA = '321'; 


6.4.5.3 Generating an Object File Containing UAR Information 


When all the forms in a form library have been modified, enter a com- 
mand of the form: 


$ FMS/VECTOR formlibraryname 


VAX FMS generates an object file that contains references to all UARs in 
the specified form files. 


6.4.5.4 Linking Your Program 


The object file containing UAR information must be linked with your 
VAX RPG II program. 
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6.5 INFDS 


The WORKSTN file INFDS is a language feature that you can use to 
handle errors on WORKSTN file operations. The INFDS data structure, 

if specified, contains status information, including errors that occurred 
and an identification of the WORKSTN operation that caused the error. 
The INFDS also contains status information on normal operations. For 
example, if a command key was pressed, that status is in the INFDS. The 
information in the INFDS is updated for each WORKSTN operation. If an 
error condition occurs, you can use the INFDS information to determine 
the type of error that occurred, then use that information to control the 
program logic. 


6.5.1 File Description Specification (F) 


To use the File Description (F) specification, you must specify the INFDS 
clause on an F specification continuation line for the WORKSTN file. The 
following program segment shows F specifications for a WORKSTN file 
and all of the continuation clauses. 


The syntax for these specifications is described in the Continuation-line 
specification. Note that there is a user-defined name (WRKINF) associated 
with the INFDS clause. 


FWRK CD F 80 WORKSTN 
F KSLN WRKSLN 
F KFMTS WRKFLB 


F KINFDS WRKINF 


6.5.2 input Specification (I) 


You must define a data structure using Input (I) specifications. The 
following example shows a data structure definition: 


IWRKINF DS 

I *STATUS WRKSTA 
I *OPCODE WRKOPC 
I *RECORD WRKREC 
I *FMSSTA WRKFST 
I *FMSTER WRKTER 


The syntax of the specifications associated with the INFDS data structure 
is as follows. 
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The first line of the input specifications includes the following: 


¢ Columns 7 through 12 contain the name of the data structure. 
¢ Column 18 may contain U, or may be blank. 
e Columns 19 through 20 must contain DS. 


e = All other fields that contain information must be blank. 


The second and following lines include the following: 


¢ Columns 44 through 51 contain one of these keywords: 


*STATUS 
*OPCODE 
*RECORD 
*FMSSTA 
*FMSTER 


¢ Columns 53 through 58 contain a subfield name. These are the names 
that will be referenced in the program. 


e = All other fields that contain information must be blank. 


The clauses shown can occur in any order, and the same keyword can . 
occur more than once. You do not need to enter all of the clauses. 


Note that this is not a general-purpose data structure; you cannot define 
other subfields in the INFDS data structure. 


6.5.3 Calculation Specification (C) 


You can refer to the various fields that are defined in a Calculation 
specification (C) within the body of the VAX RPG II program. This is of 
particular importance in user-defined error handling. 
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6.5.4 


«STATUS Keyword 


The *STATUS keyword identifies a one-digit numeric subfield with zero 
decimal positions within the INFDS data structure. This subfield contains 
a code that identifies the status of the last WORKSTN file operation. The 
codes are as follows: 


Code Definition 


0 No error (form input was terminated by pressing the ENTER key or the 
RETURN key) 


Command key (form input was terminated by a command key) 
Function key (form input was terminated by a function key) 


3 Error 


Any code in *STATUS greater than 2 is considered to be an error con- 
dition. If an error occurs on a READ operation code that has an error 
indicator, the indicator is set on. If in error occurs on the following 
operations, the program will terminate. 

¢ A READ operation code with no error indicator 

e A primary file read 

¢ Normal output 

¢ EXCPT output 


*OPCODE Keyword 


The *OPCODE keyword identifies a five-character alphanumeric subfield 
within the INFDS data structure. This subfield contains a value that 
identifies which WORKSTN operation was executing when the error 
occurred. The value inserted in the *OPCODE subfield is OPEN, CLOSE, 
READ, or WRITE. A value is inserted in the *OPCODE subfield on each 
WORKSTN file operation. 
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6.5.7 


*RECORD Keyword 


The *RECORD keyword identifies an eight-character alphanumeric 
subfield within the INFDS data structure. If *OPCODE contains WRITE, 
then *RECORD contains the current form name!. Otherwise, *RECORD 
contains blanks. | 


*FMSSTA Keyword 


The *FMSSTA keyword identifies a longword integer (binary) numeric 
subfield with zero decimal positions within the INFDS data structure. This 
subfield indicates the general status returned by the last VAX FMS Form 
Driver call. 


*FMSTER Keyword 


The *FMSTER keyword identifies a word integer (binary) numeric subfield 
with zero decimal positions within the INFDS data structure. This subfield 
indicates the field terminator entered by the operator to terminate input to 
the form. If the form was terminated by pressing the RETURN key or the 
ENTER key, this subfield will contain a value of 0. See the VAX FMS Form 
Driver Reference Manual for terminator codes. 


Other Subfields 
VAX RPG II does not support the following INFDS subfields: 
e SIZE 
e MODE 
e INP 
e¢ OUT 


¢ MAJOR/MINOR 


1 Only the first eight characters of the current form name are in *RECORD. 
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6.6 Example Program Development Cycle 


The previous sections of this chapter have described various features of 
VAX RPG II screen handling. This section will use an example to step 
through the various program development steps that can be performed 
to produce a running interactive application using VAX RPG II and VAX 
FMS. 


The following example shows the VAX RPG II program INVENT that 
includes three VAX FMS forms: 


¢ PARTNUMBER 
¢ PART_UPDATE 
¢ PART_ERROR 


The program uses the following indexed file INVENT.DAT: 


ee es 


POANUT W2RED 0300135 
PO2BOLT W2GREENO880167 
PO3SCREW W1BLUE 0180048 
PO4SCREW W2RED 0150143 
POSCAM W1IBLUE 0130205 
PO6COG W3RED 0200215 
POTGEAR W3GREY 0100234 
POSBEARINGW2GREY 0260136 
POO9BOLT WiWHITEO060015 


The goal of the program is to allow you to select parts from the INVENT 
file and display the inventory information for the part, with the possibility 
of entering updated data. The PART_NUMBER form will be used to 
retrieve the three-character part number that will be used as the key into 
the INVENT file to retrieve the inventory information. The 
PART_UPDATE form will be used to display the inventory information 
if the part number is located in the inventory. PART_UPDATE will also 
allow you to update any inventory field except the part number. 
PART_ERROR will display an 2rror message if an invalid part number 
is entered. The program will terminate when a part number of P00 is 
entered. 


First, the forms will be defined using the VAX FMS Form Editor Utility to 
create the PART_NUMBER as follows: 


$ FMS/EDIT PART_NUMBER 
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The editing session allows any constant text or labels to be placed on 

the form. A one-character field to contain the form code is defined. This 
technique is used often in RPG, when multiple input forms are allowed, to 
distinguish between the various forms in the Input specifications. You will 
see later in the program how the form code is initialized for each input 
form. 


The input field for the part number is then defined to contain three 
characters. This field is defined with X99 in VAX FMS to select only part 
numbers ending with two numbers. As part numbers are entered, 

VAX FMS will verify that the last two digits are numeric. A prompt for 
the part number is defined as constant text. 


After exiting the VAX FMS Form Editor Utility, you can obtain information 
about this first form using the /DESCRIPTION qualifier: 


$ FMS/DESCRIPTION/BRIEF PART_NUMBER 


VAX FMS Form Description Application Aid - V2.2 - Brief Description 


Form Name = PART_NUMBER 

No Help Form 

Area to Clear = 1:1 

Memory Resident Form Size = 262 


Field Name (Max Index) Pic(Length) Access UARs 
FORM_CODE X(1) DISP 
PN X(3) 


Total Length Required = 4 
Longest Field = 3 


No Named Data 


No User Action Routines 


Two additional VAX FMS editing sessions are used to create 
PART_UPDATE.FRM and PART_ERROR.FRM. You can then get a brief 
text description of these forms using this command: 


$ FMS/DESCRIPTION/BRIEF PART_UPDATE 


FMS Form Description Application Aid - V2.2 - Brief Description 


Form Name = PART_UPDATE 

No Help Form 

Area to Clear = 1:23 | 

Memory Resident Form Size = 554 
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Field Name (Max Index) Pic(Length) Access UARs 


sem w ewe wee eee ew ew wee ee eee eee we wm wee wee] wens eww woe wa2ncre eo 


FORM_CODE X(1) DISP 
PN X(3)—- DISP 
PNAME © (7) 
WHOUSE C(2) 
COLOR C(5) 
WEIGHT 9(3) 
QTY 9(4) 


Total Length Required = 25 
Longest Field = 7 


No Named Data 


No User Action Routines 
$ FMS/DESCRIPTION/BRIEF PART_ERROR 


FMS Form Description Application Aid - V2.2 - Brief Description 


www mm mmm em eee w wwe ee eee me mem mmm meee meme me ee ee mee we wee wee wee ee meee mmo oos 


Form Name = PART_ERROR 
No Help Form 


Area to Clear = 2:23 
Memory Resident Form Size = 146 


Field Name (Max Index) Pic(Length) Access UARs 


ee meme me ewe meme em we momem eee eee ee ee em mewn wow ew ew eoons wewnrewee eoenwe 


F$0002 C(22) 


Total Length Required = 22 
Longest Field = 22 


No Named Data 


No User Action Routines 


You can then create the form library as follows: 


$ FMS/LIBRARY/CREATE PARTS PART_NUMBER, PART_UPDATE, PART_ERROR 
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Next, you develop the VAX RPG II program that will be used to access 
these forms and the inventory data file: 


140FPARTS CD F 
Q0FINVENT UC F 


3OLINVENT 
401 

5OIPARTS 

601 

701 

801 

QOIDATA 

1001 

1101 

1201 

1301 

1401 

1501 

4160C 

170C 

180C 

190¢ 99 
200C 99NLR 
210C N99 
2200 N99 
230C N99 
2400PARTS E 
2500 

2600 

2700 

2800 E 
2900 

3000 

3100 

3200 E 
3300 

3400 
3500INVENT E 
3600 


01 
02 


DS 


PN 
PN 


1 CA 


25. WORKSTN 
24R 3AI 1 DISK 


1 CB 


24 DATA 
4 PN 
25 DATA 


3 PN 
10 PNAME 
12 WHOUSE 
17 COLOR 
200WEIGHT 
240QTY 


99 
LR 


K 'PART_NUMBER' 


K 'PART_UPDATE' 


K ‘'PART_ERROR' 
22 'No part by that number' 


2 
2 
1 
4 
11 
13 
18 
21 
EXCPTP_NUM 
READ PARTS 
CHAININVENT 
COMP 'POO' 
EXCPTP_ERR 
EXCPTP_UPD 
READ PARTS 
EXCPTINV 
P_NUM 
PN 4 
1 ‘A’ 
P_UPD 
DATA 25 
1 'B' 
P_ERR 
INV 
DATA 24 


The WORKSTN file is defined on line 10 as a combined demand file. The 
record length of 25 is chosen based on the longest form buffer required. _ 
This value is obtained from the ‘Total Length Required’ item listed as part 
of FMS/DESCRIPTION/BRIEF for each form in the library. 


Line 20 shows the definition for the inventory file that will be indexed, 
updated, shared, and accessed using the CHAIN operation. 


The data layout for the inventory file is given in the data structure on lines 
90 through 150 and referenced in the input record on lines 30 through 40. 
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Lines 50 through 80 show the definition of the form that provided the 
input. The first character in the WORKSTN file record buffer is examined 
to see if it is ‘A’ or ‘B’. Note that lines 270 and 310 place an ‘A’ or ‘B’ 
into the first position of the WORKSTN file record buffer. This first byte 
corresponds to the FORM-_CODE field, specified as part of the two input 
forms, but not displayed on these forms. This special FORM—CODE byte 
is stored to provide a means for the Input specifications to determine the 
last input form. You can use other methods, such as field record relation 
indicators on Input specifications, to determine the current input form. 


Lines 240 through 340 show the lines that output forms to the screen. 

The three forms are listed, along with an EXCPT name, to make it easy 
to select the appropriate form for display. Note that data is placed in 

the WORKSTN record buffer in lines 260 through 270, 300 through 310,. 
and line 340. The ending positions for these fields match the information 
obtained with FMS/DESCRIPTION/BRIEF. The ending position for DATA 
in line 300 is 25 because the initial byte for the FORM—CODE is not 
included as part of the DATA data structure. 


Lines 160 through 230 include the actions performed during each logic 
cycle. First, the PART_NUMBER form is displayed on line 160. Then, 
input is requested from that form on line 170. The part number obtained 
is used on line 180 to retrieve the part information from the inventory 
file. Line 190 determines if the program should terminate, and line 200 
displays the error form for any part number that was in error. Lines 210 
through 220 display valid part information and allow you to update part 
information that is returned to the program by the READ operation in line 
220. Finally, the inventory file is updated on line 230, and the cycle is 
repeated until a part number of P00 is supplied. 


You can then compile, link, and run the program as follows: 
$ RPG INVENT 

$ LINK INVENT, SYS$LIBRARY : RPGSCR 

$ RUN INVENT 


Note that you include SYS$LIBRARY:RPGSCR only when you link 
programs that use a WORKSTN file. This object module contains the 
run-time support to interface with VAX FMS. 


The program does not need to be run on a VAX/VMS evel with 
VAX RPG II installed. 
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You may wish to create an object module library by logging in to the 
SYSTEM account and setting the default to [SYSLIB]. Then use the follow- 


ing command: 


$ LIBRARIAN/CREATE RPGSCR RPGSCR 


Then, each VAX RPG II user may set up the following logical: 


$ DEFINE LNK$LIBRARY SYS$LIBRARY :RPGSCR 


This logical definition eliminates the need for explicit references to 
RPGSCR on LINK commands. If the necessary logicals are not de- 
fined, or if you do not properly link your program files, you may get an 


error message that RPG$SCR is undefined. 


If you link a program with a 


WORKSTN file and get a message that FDV$ATERM is undefined, you are 
attempting to link on a system that does not have VAX FMS installed. 


The following program shows a WORKSTN primary file. This is an 
example of a display-only application; you are not allowed to update the 


inventory information in this case. 


FPARTS CP F 25 WORKSTN 

FINVENT IC F 24R 3AI 1 DISK s 
TINVENT 02 

I 1 24 DATA 
IPARTS 01 1CA 

I 2 4 PN 
IDATA DS 

I 1 3 PN 

I 4 10 PNAME 

I 11 12 WHOUSE 
I ‘13 17 COLOR 

I 18 200WEIGHT 
I 21 240QTY 

Cc PN CHAININVENT 99 

Cc 99 PN COMP 'POO' LR 
OPARTS D 99 

0 K 'PART_ERROR' 

0 NLR 22 'No part by that number' 
0 LR 22 'Exit requested' 
0 D 02 

0 K 'PART_UPDATE' 

0 DATA 25 

0 1 'B! 

0 D NLR 

0 K '‘PART_NUMBER' 

0 PN 4 

0 1 'A' 
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6.7 Converting from S and D Specifications 


Some RPG implementations provide a method for describing forms with 
Screen and Display specifications. These specifications have information 
similar to that available in the VAX FMS Form Language. Many of the 
fields in the Screen and Display specifications can be converted to the 
VAX FMS Form Language using the VAX RPG II Conversion Utility as 
follows: 


$ RPG/CONVERT=SD_TO_FMS s-and-d-file 


The input to the Conversion Utility is a file containing Screen and Display 
specifications for one or more forms. The output is 0 or more VAX FMS 
Form Language files (with the FLG file type) containing the VAX FMS 
Form Language. This corresponds closely to the Screen and Display speci- 
fication description of the forms. Certain Screen and Display specification 
features cannot be represented in the VAX FMS Form Language, but must 
be handled separately. These features include: 


e Use of screen line 24 

e Sand D specification RPG indicators 

° Multiple input constants 

e¢ Output/no input fields 

After the Conversion Utility has created the VAX FMS Form Language 
files, FAS/TRANSLATE and FMS/LIBRARY can be used. You can then 


modify the forms either by modifying the FLG files, or by using the 
VAX FMS Form Editor Utility. 


6.7.1 S and D Specification Conversion Utility 


The input to the SD converter is a single file containing Screen and 
Display specifications for 0 or more forms. The output is 0 or more FLG 
files based on the SD specifications. Each group of SD specifications 
produces one file with the FLG extension. 
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6.7.1.1 Invoking the Conversion Utility 
The Conversion Utility is invoked with the following qualifier: 
$ RPG/CONVERT=SD_TO_FMS/NODISPLAY file-spec 


The /CONVERT=SD_TO_FMS qualifier can be abbreviated to 
/CONVERT because the default is SD-TO_FMS. Also, /NODISPLAY 

is required only if the Conversion Utility is run in batch mode, or on a 
terminal with no TPU support. If you omit /NODISPLAY, the screen will. 
be cleared before the Conversion Utility begins. 


To save typing, the following symbol is recommended: 
$ RPGCNV :== RPG/CONVERT=SD_TO_FMS/NODISPLAY 


If you define this symbol on your system, the Conversion Utility can be 
called with the following command: 


$ RPGCNV file-spec 

The Conversion Utility can also be invoked with the following command: 
$ EDIT/TPU/NODISPLAY/SECTION=RPGCONVERT file-spec 

You can get help by typing the following: 


$ HELP RPG Conversion (or) 
$ HELP RPG /CONVERT 


To abort the RPG/CONVERT command operation, press CTRL/Y. 


6.7.1.2 Overview of Converter Utility Operation 


After you invoke the Conversion Utility, a message will be displayed 
that shows the file specification and the number of lines that were input 
from the file containing the Screen and Display specifications. The default 
file type is SD for the input file. Each Screen specification defines a 
single form that is output as an FLG file. All Display specifications 
following a Screen specification are output as fields in the FLG. If no 
Screen specification is seen, no FLG file is created. 


If anything other than a comment, or Screen, Display, or Help specification 
is seen, the input line is output to SYS$OUTPUT, along with the following 
message: 


%RPG-W-SPEC_IGNORED, specification was not an S or D spec 


Any noncontinuation line with an asterisk in column 7 is recognized as a 
comment. There is no VAX RPG II support for Help specifications. 
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An input line that cannot be completely translated into the VAX FMS 
form language is output to SYS$OUTPUT, along with a message in the 
following form: 


“RPG-W-COLS_IGNORED, columns ai-a2,a3-a4 have been ignored 


For example, if columns 37 through 38 and 49 cannot be translated 
into the VAX FMS Form Language for a Display specification, then the 
following message is displayed: 


“4RPG-W-COLS_IGNORED, columns 37 to 38,49 have been ignored 


In certain cases, additional messages beyond the three mentioned previ- 
ously will be issued. 


If you use a field that is not translated to the VAX FMS Form Language, it 
is possible that the field will be used on many Display specifications. 
VAX RPG II will report the error on all specifications that have the field 

_ that is being ignored, to enable you to check off Screen and Display 
specifications as the manual conversion (if necessary) is completed. 


Note that the output from the converter is a text file. If you wish to use 
an interpretation for a Screen or Display specification field that is different 
from that used by the converter, you can make any necessary adjustments 
to the VAX FMS Form Language text file that is output by the converter. 
You can also use the VAX FMS Form Editor Utility to make any desired 
modifications to the form after the form language is translated. 


6.7.1.3 Screen Specification (S) 


Columns 1 through 5 are not examined in the Screen specification. If 
column 6 specifies S, then the specification is recognized as a Screen 
specification, and the processing takes place. If column 7 is an asterisk 
(*), the Screen specification is ignored. 


The following table identifies the significant Screen specification columns 
and the corresponding VAX FMS Form Language that is output. All other 
Screen specification columns are ignored. The VAX FMS Form Language 
used is a close approximation of the Screen specification meaning. In 
many cases, the exact functionality of a Screen specification feature cannot 
be duplicated with VAX FMS. 
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Begin End S Spec VAX FMS Interpretation 


7 14 name FORM NAME 

17 18 01-24 FORM START LINE (defaults to 1) | 

19 20 00-24 AREA—TO_CLEAR (specified on S specifica- 
tion as lines to clear) . 

21 not Y ' UPPERCASE on all fields 

28 Y RPG$ENABLE_KEYS defined for each letter 
in columns 64-79 

N RPG$DISABLE_KEYS defined for each letter 


in columns 64-79 


Your FORM START LINE must be constant and less than 24. If you use 
a FORM START LINE greater than 23, it will be converted to 23. Your 
AREA_TO_CLEAR must go no higher than 23, otherwise a value of 23 
is used. The default value for the START of the AREA_TO_CLEAR is 1, 
and you cannot use a value less than 1. The AREA~TO_CLEAR_ STOP 
must be at least as large as the AREA_TO_.CLEAR_START, or no 
AREA—TO_CLEAR clause will be output. Note that START line 1 and 
AREA_TO_CLEAR 23 is the same as leaving AREA_TO_CLEAR blank. 


In addition, BACKGROUND=CURRENT is output for each form. 


The converter outputs a NAMED_DATA statement when you specify 
either selective enabling or disabling. For each capital letter that you put 
in columns 64 through 79 of the Screen specification, a number indicating 
the key value of the corresponding VAX FMS terminator is output in 

the data clause. These are the same default encodings used to describe 
command keys. Note that if you do not use the default command key 
definitions, you will need to define the logical name 
RPG$COMMAND_KEYS and modify the RPGSENABLE_KEYS or 
RPG$DISABLE_KEYS named data items appropriately. 
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6.7.1.4 Display Specification (D) 
Columns 1 through 5 are not examined. 


The letter D in column 6 indicates that this is a Display specification. 
Display specifications must be preceded by a Screen specification. If no 
Screen specification is included, the Display specification is ignored, and 
the following warning is issued: 


%RPG-W-SPEC_IGNORED, D specifications must follow an S spec 


If column 7 is an asterisk (*) the Display specification is ignored, unless 
the Display specification is a continuation line as described below. 


If the previous Display specification had any nonblank character in 
column 80, then the remainder of the Display specification is processed 
as a continuation of the previous specification. Otherwise, if column 7 is 
an *, it is recognized as a comment, and the rest of the specification is not 
examined. 


The following table gives the Display specification columns and the 
corresponding VAX FMS Form Language that is output. All other Display 
specification columns are ignored. The VAX FMS Form Language used 

is a close approximation of the Display specification meaning. In many 
cases, the exact functionality of a Display specification feature cannot be 
duplicated with VAX FMS. . 


Begin End D spec VAX FMS Interpretation 

7 14 name FIELD NAME 

15 18 > 0 PICTURE (field length) 

19 20 > 0 Screen line number (based on Screen 


specification starting line). Any line number 
greater than 23 is converted to 23. 


21 22 01-99 Screen column number 
26 Y Input field 
27 Data validation 

A A 

N N 

D 9 
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Begin 


28 
29 
31 
35 


39 
41 
43 
45 
47 
49 


51 


End 


44 


D spec 
(other) 


KKK ZK KK 


blank 


VAX FMS Interpretation 


X (Note that you must manually convert S 
on the Display specification. The VAX FMS 
record buffer will use the length as specified 
on the Display specification. The sign must 
be placed in the last byte position for fields 
to be displayed. There is no automatic data 
conversion that overpunches the sign on 
data input or decodes an overpunched sign 
on data output.) 


MUST_FILL 
RESPONSE_REQUIRED 
RIGHT_JUSTIFIED 


AUTO_TAB (column 26 on Display specifi- 
cation must also be Y) 


BOLD 
BLINKING 
NOECHO 
REVERSE 
UNDERLINE 


UNDERLINE (this handles column separa- 
tors) 


UPPERCASE 


Indicators anywhere on Display specifications are ignored. If column 56 is 
C or P, or columns 57 through 79 are nonblank, then columns 57 through 
79 are interpreted as VAX FMS background text (except in the case where 
column 26 is Y). Input constants are handled as VAX FMS NOECHO 

DISPLAY_ONLY fields. 


6.7.2. Manual Conversion 


If you manually convert from Screen and Display specifications, there are 
several items to observe that are described in the following sections. 


6-30 VAX RPG Ii Screen Handling 


6.7.2.1 Use of Line 24 


- VAX FMS reserves line 24 on the terminal screen for messages. No field 
or constant text can be placed on line 24. Because the converter changes 
line 24 references to line 23, a conflict could arise if line 23 is already 
being used. The FMS/TRANSLATE operation will issue an error message 
if any conflicts are detected. 


6.7.2.2 Duplicate Field Names 


If two Display specifications for the form contain the same field name, you 
will get the following errors from FMS/TRANSLATE: 


%FMS-E-DUPFLDNAM, Field name {field-name} was already specified; 
' default name has been assigned. 
“4FMS-E-ENDNOFRM, Translation was completed with errors. 

No binary form was output. 


This-is because VAX FMS requires unique field names. You can correct 
the error by first making the field names unique in the file containing the 
Display specifications, and then rerunning the S and D Conversion Utility. 
Or, you can modify the VAX FMS Form Language file so that all field 
names in a form are unique. 


6.7.2.3 S and D Specification VAX RPG II Indicators 


All occurrences of VAX RPG II indicators in Screen and Display specifi- 
cations are ignored by the converter. A diagnostic will be issued by the 
converter for each use of VAX RPG II indicators. You can handle many of 
the uses of VAX RPG II indicators by conditioning indicators in the VAX 
RPG II program. 


6.7.2.4 Record Buffer Layout 


Display specifications provide a way for specifying fields that will be input 
and not output, and fields that will be output but not input. Thus, Display 
specifications provide you with two alternative record buffer layouts. 

VAX FMS provides a single consistent record buffer layout for both input 
and output fields. The messages shown in the next sections will be 
displayed for those Display specification fields that may require some 
modification in the program Input or Output specifications. 
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To verify the correct field layout, use FMS/DESCRIPTION/BRIEF to 
display the field layout for the form in VAX FMS format and match the 
layout to the program Input and Output specifications for the form. Note 
that the first input constant (if any) will be automatically handled at run 
time. The VAX FMS record buffer layout will not show the first input 
constant. 


6.7.2.5 Multiple Input Constants 


If more than one field has been encountered which has a Y in Display 
specification column 26, and with a letter other than Y in Display specifi- 
cation column 23, the following message is displayed: 


%RPG-E-MORE_CONVER, (1) At most one input constant in a form is converted. 


This type of field is referred to as an input constant. Many programs with 
multiple input forms use an input constant so that each form will be able 
to identify itself when input is done. The converter automatically handles 
one input constant in each form by creating VAX FMS named data: 


RPG$CONSTANT_TEXT 
RPG$CONSTANT_LENGTH 
RPG$CONSTANT_START 


This data will be used at run time to adjust the field layout so that it can 
accommodate the input constant. No manual conversion is needed for this 
first input constant. However, some forms might use two input constants. 
The MORE_CONVER error message will be displayed if more than one 
input constant is used. The manual conversion involves adjusting the 
Output specification ending positions for the form to allow space for the 
input constant. You must list the input constant as an Output specification 
constant. 


6.7.2.6 Output and No Input Fields 


If a field has been encountered which has a Y in Display specification 
column 23 and with a letter other than Y in Display specification column 
26 (that is followed by an input field), the following message is displayed: 


| %RPG-E-MORE_CONVER, (1) Output / no input fields may require I specification changes. 


This type of field receives output data but no input data. VAX RPG II will 
allow space in the record buffer for these forms. Even though the form 
will have the field marked as display only, VAX FMS expects space to 

be allocated in the WORKSTN record buffer for both Input and Output 
specifications. There is no automatic conversion for any use of output and 
no input fields. | 
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Chapter 7 
Using Indicators 


Indicators are two-character alphabetic, numeric, or alphanumeric entries 
that condition certain operations within the steps of a normal program 
cycle. Generally, you use indicators to control the following program 
decisions: 


¢ Under what conditions VAX RPG II uses a file during program execu- 
tion 

e When and under what conditions VAX RPG II performs calculations 

e When VAX RPG II can access a field for input 

e Under what conditions VAX RPG II writes a field or record to an 
output file 

This chapter describes types of indicators and explains how to use them. 


Section 7.1 describes those indicators that are user-defined within a 
program. Section 7.2 describes internally defined indicators. Section 7.3 
describes how to use indicators as fields. 


7.1 User-Defined Indicators 


Each indicator has a specific function; however, some indicators can be 
user-defined for more than one function. 


To use an indicator to control program operations, you must first define 
the conditions under which it is set on or off. Then, check the status 
(on or off) of the indicator to determine what steps your program should 
perform. 
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7.1.1 Record-identifying Indicators 


Record-identifying indicators are used to distinguish the types of input 
records that will be encountered within your program at run time. 


You must first define each record type by specifying an identification code 
in columns 21 through 41 of the Input specification. Then, associate one 
of the following indicators with each record type in columns 19 and 20 of 
the Input specification: 

e 01 through 99 

e L1 through L9 

e LR 

e Hi through H9 


In the following example, VAX RPG II associates the record-identifying 
indicator 01 with a record type: 


Sequence (AA-ZZ, 01-99) 
| Number (1-N) 





| lOptional/External (OU) Decimal positions 
| (lRecord identifying indicator | Control level 
r ttl | | Match field 
1 {tl + Identifying codes + Format | | | Fld rec rel 
File 1 iti t 1 | (PB) IField | J | 
nane 1 ttl | ¢C ¢ Cl tField tIname | 1 1 Field 
| Lut | Z Z Z| llocation! | | | | indicatrs 
wl | 111 Pos NDePos NDcPos NDc IFr_ To II Dib <0 
) 2 3 4 | 6 
901234567 
#% Te en ne ne | ee eT) ERNHH HOLL, 
IINPUT AA O01 20 Ci 
ZK-4387-85 


In this example, if the character in the twentieth position is the number 
1, the indicator 01 is set on. Then, you can use the indicator to condition 
program operations for that particular record type. 


The record-identifying indicator for a particular record type is set on when 
VAX RPG II processes a record of that type. For a primary or secondary 
file, the record-identifying indicator is set on before total-time calculations. 
For a chained or demand file, the record-identifying indicator is set on 
immediately after the record is read. (See Chapter 8 for information on 
file usage with VAX RPG II.) In either case, it is set off when the program 
reaches the end of the current program cycle (after detail-time output). 


7-2 Using Indicators 


You can use record-identifying indicators to condition both detail-time 
and total-time calculation and output operations for each record type. The 
following example shows how record-identifying indicators can be used to 
condition program operations: 


0 4 koe ue | 3 | 4 I 4) | 6 | Z | 





123456 789012345678901234567890123456 7890123456 7890123456 7890123456 7890123456 7890 


44 ISALES AA OL 1 CJ 


{2 I 2 SOITEM 
13 I 10 16 DESCR 
14 1 20 242SALES 
15 I 30 342COST 
16 I 40 432PROFIT 
i7c O41 SALES SUB COST NET 52 

isc of TSALES ADD SALES TSALES 62 

i9¢ Ot TCOST ADD COST TCOST 62 

20 ¢ TPROF I ADD NET TPROFI 62 

21 OREPORT H 204 1P 

22 0 OR OF 

23 0 UDATE Y 8 

24 0 44 ’ JANUARY SALES REPORT’ 
25 0 PAGE 72 

26 0 68 ’PAGE’ 

e7 0 H 22 iP 

28 0 OR OF 

29 0 5 ‘ITEM’ 

30 0 23 ‘DESCRIPTION’ 
31 0 41 ‘SALES’ 

32 0 56 ‘COST’ 

33 0 72 ‘PROFIT’ 

34 0 D 01 

35 0 ITEM 3 5 

36 0 DESCR 25 

37 0 SALES 1 41 

38 0 cost 1 57 

39 0 PROFITL 72 

40 0 T 1 LR 

410 30 ‘TOTALS’ 

42 0 TSALESL 41 '$’ 

43 0 TCOST 1 «57 7$’ 

440 TPROFIL 72 '$’ 
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In the preceding example: 


e Line 11 causes VAX RPG II to begin reading records from the file 
SALES. The identification code (columns 21 through 41) groups these 
records according to a code that represents the month. If the code for 
the month is J, the record-identifying indicator 01 is set on. 


e Lines 17 through 19 use the same record-identifying indicator 01 
to condition detail-time calculations. VAX RPG II performs the 
calculation each time a record of the type described on line 11 is 
read: 


e Line 34 uses the same record-identifying indicator to condition detail- 
time output. VAX RPG II performs the output operation each time a 
record of the type described on line 11 is read. 

The output file produced by this program might appear as follows: 


0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 


123456789012345678901 2345678901 2345678901 23456789012345678901 2345678901 234567890 
2/4/83 JANUARY SALES REPORT PAGE i 
ITEM DESCRIPTION SALES COST PROFIT 

10005 AMMONIA 60.30 50.00 10.30 

10982 MATCHES 295 .00 205 .00 90.00 

22650 NUTMEG 209.00 170.00 39.00 

TOTALS $564.30 $425.00 $139.30 


If you use the CHAIN or READ operation to retrieve records, the program 
does not set the record-identifying indicators off until the beginning of the 
next program cycle. Be careful when performing more than one CHAIN 
or READ operation for a file with multiple record types, because more 
than one indicator can be set on during a single cycle. 


7.1.2 Field Indicators 


Field indicators test a field in an input record for a positive, negative, zero, 
or blank value. 


You can use any of the following indicators as field indicators: 

e 01 through 99 

e = H1 through H9 

Field indicators are used to test the value of a field in the following ways: 


e For a positive value, specify a field indicator in columns 65 and 66 of 
the Input specification. 
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e For a negative value, specify a field indicator in columns 67 and 68 of 
the Input specification. 


e For a zero or blank value, specify a field indicator in columns 69 and 
70 of the Input specification. 


Field indicators are set when the data in the field is extracted from the 
record. After a field indicator is set on, it remains on until the next 
time the field is extracted, unless it is set off by another use of the same 
indicator in the program. A field indicator can be used to condition any 
detail-time or total-time operations. However, at total time, the field 
indicators assigned to fields from a primary or secondary file retain the 
setting from the previous detail-time cycle. 


The following example shows how field indicators can be used to 
condition a calculation: 


| 4° | 5 | 6 ri | 





0 | 1 I é | 
12345678901234567890123456 7890123456 7890123456 7890123456 7890123456 78901234567890 


24 IPARTLIS AA 01 1 CF 


25 I 2 100INVCDE 112233 
4c Af ITEM MULT FACT1 ORDER 62H 
42 C 22 ITEM MULT FACT2 ORDER 62H 
43C 33 ITEM MULT FACT3 ORDER 62H 
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In the preceding example: 


e Line 25 tests the value of the field INVCDE to see if it contains a 
positive value, a negative value, or a zero value. The following is a 
list of indicators that are set on for each value: 


— If the field contains a positive value, indicator 11 is set on and 
indicators 22 and 33 are set off. 
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— If the field contains a negative value, indicator 22 is set on and 


indicators 11 and 33 are set off. 


— If the field contains a zero value, indicator 33 is set on and 


indicators 11 and 22 are set off. 


Lines 41 through 43 calculate the number of parts to order according 
to the status of the field indicators. 


7.1.3 Resulting Indicators 


Resulting indicators condition operations that depend on the result of a 
calculation. These indicators specify the test (> , <, or =) and indicate 
the result of the calculation. If the result matches the test, the indicators 
are set on. The indicators are set off if the next instance of that calculation 
does not satisfy the indicated test or if the same indicator is used again in 
the program. 


You specify resulting indicators in columns 54 through 59 of the 
Calculation specification. You can use any of the following indicators 
as resulting indicators: 


01 through 99 

L1 through L9 

LR 

H1 through H9 

OA through OG, and OV 
U1-U8 

KA through KZ 

KO through K9 


Resulting indicators in columns 54 and 55 test for the following conditions: 
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The result field contains a positive value after an arithmetic operation. 


When comparing two factors, the value in factor 1 is higher than — 
value in factor 2 in a COMP operation. 


The value of the element found in factor 2 is higher than the value in 
factor 1 in a LOKUP operation. 


The record is not found in a CHAIN operation. 


Each bit defined in factor 2 is set off in the result field for a TESTB 
operation. 


Resulting indicators in columns 56 and 57 test for the following conditions: 


The result field contains a negative value after an arithmetic operation. 


The value in factor 1 is lower than the value in factor 2 in a COMP 
operation. 


The value of the element found in factor 2 is lower than the value in 
factor 1 in a LOKUP operation. 


The defined bits in factor 2 are of mixed status (some on, some off) in 
the result field for a TESTB operation. 


A subprogram returns with an error status from a CALL operation. 


A READ operation is executed on a WORKSTN file, and an error other 
than EOF occurred. 


Resulting indicators in columns 58 and 59 test for the following conditions: 


The result field contains a zero after an arithmetic operation. 

The value in factor 1 is equal to the value in factor 2 in a COMP 
operation. . 

The value of the element found in factor 2 is equal to the value in 
Factor 1 in a LOKUP operation. 

An end-of-file condition occurs for the demand file in a READ opera- 
tion. 

A READ operation is executed on a WORKSTN file and the last form 


displayed has no input fields, or no form has been displayed since the 
previous READ. | 


Each bit defined in factor 2 is set on in the result field for a TESTB 
operation. 


Resulting indicators are also used with the SETON and SETOF operation 
codes to specify that the indicators are to be set on or off. 
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The following example shows how resulting indicators can be used to 
control program operations: 


Field length 





Control level | Decimal positions 
. 1 [Half adjust (H) 
| Indicators Operation f dl 
1 | | | JlResulting 
1 | Factor | Factor Result! {lindicators 
1 | i | 2 field | Il+- 0 
Cl NxxNxxNxx | I | | | Ii> < = +- Comments --+ 
| 7 | 
HH % ¥ H--KEX HOEK 
10 ¢ SEARCH LOKUPTAB1 40 14 
20 C FLD4 COMP 100 222324 
30 C¢ KEY CHAINFILE4 32 
40 C TESTB’123’ TEST 404142 
50 C READ FILE{ 50 
60 C SETOF 1014 
70 C FLD4 SUB FLD2 RES 606162 
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In the preceding example: 
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Line 10 causes VAX RPG II to search for field SEARCH in table TAB1. 
If VAX RPG II can find an entry that is equal to the search word, 

indicator 11 is set on. If VAX RPG II can find an entry that is nearest 
to and higher in sequence than the search word, indicator 10 is set on. 


Line 20 causes VAX RPG II to compare the contents of FLD1 with 
the numeric literal 100. If the contents of FLD1 are greater than 
100, indicator 22 is set on and indicators 23 and 24 are set off. If 
the contents of FLD1 are less than 100, indicator 23 is set on and 
indicators 22 and 24 are set off. If the contents of FLD1 equal 100, 
indicator 24 is set on and indicators 22 and 23 are set off. 


Because the input file is an indexed file, line 30 instructs VAX RPG II 

to retrieve a record using the key KEY from the indexed file FILE1. If 
the record is not found, indicator 32 is set on. Otherwise, indicator 32 
is set off. 


Line 40 causes VAX RPG II to test the bits 1, 2, and 3 in TEST. If the 
bits are all off, indicator 40 is set on and indicators 41 and 42 are set 
off. If some bits are on and some are off, indicator 41 is set on and 
indicators 40 and 42 are set off. If the bits are all on, indicator 42 is 
set on and indicators 40 and 41 are set off. 


¢ Line 50 causes VAX RPG II to read the next record from FILE1. If 
an end-of-file condition occurs, indicator 50 is set on. Otherwise, 
indicator 50 is set off. 


e Line 60 sets indicators 10 and 11 off. 


e Line 70 causes VAX RPG II to evaluate the contents of the result field 
after the SUB operation. If the result field contains a positive value, 
indicator 60 is set on and indicators 61 and 62 are set off. If the result 
field contains a negative value, indicator 61 is set on and indicators 60 
and 62 are set off. If the result field contains a zero value, indicator 62 
is set on and indicators 60 and 61 are set off. 


7.1.4 Control-Level Indicators 


Control-level indicators indicate that a particular field in the input record 
is a control field. Each time VAX RPG II reads a record that contains the 
control field, it compares the data in the control field with the current 
value of the control field. If the contents change, a control break occurs, 
the control-level indicator is set on, and the value in the control field 
becomes the new current value. 


You associate a control-level indicator (L1 through L9) with an input field 
by specifying the indicator in columns 59 and 60 of the Input specification. 


The lowest control level indicator is L1 and the highest is L9. When you 
use more than one control-level indicator and a higher level control-level 
indicator is set on because of a control break, VAX RPG II automatically 
sets on all lower level control-level indicators. When you use a control- 
level indicator as another type of indicator (for example, as a record- 
identifying indicator), and that indicator is set on, lower level control-level 
indicators are not automatically set on. 


A control break is likely to occur after the first record with a control field is 
read. VAX RPG II compares the data in the control field with hexadecimal 
zeros. Therefore, VAX RPG II bypasses total-time calculation and output 
operations for the first record containing control fields. 


All control-level indicators are set on before total-time calculations when 
the last-record (LR) indicator is on. All control-level indicators a are set off 
after detail-time output. 
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The following example shows how to use three different control-level 
indicators to condition calculation and output operations: 





0 | | | 2 | 3 1 ry | 5 | 6 I 7 | 
123456789012345678901234567890123456 78901 23456 7890123456 789012345678901234567890 
H 

2 FSLSCAR IP F 14 DISK 
3 FSLSREP O F 132 OF PRINTERTMP 
4 ISLSCAR AA O14 
5 I 1  20BRANCHL3 
61 3. 40SLSPERL2 
7 I 5 9O0CUSTNOLS 
8 I 40 442SLSAMT 
9c O1 SLSAMT ADD CUSTOT CUSTOT 62 
10 CLi CUSTOT ADD SPTOT SPTOT 72 
11 Cle SPTOT ADD BRTOT BRTOT 72 
42 CL3 BRTOT ADD FINTOT FINTOT 82. 
43 OSLSREP H 204 {P 
14 0 OR OF 
15 0 UDATE Y 9 
16 0 25 ’SALES REPORT’ 
17 0 38 'PAGE’ 
18 0 PAGE 43 
19 0 H 1 iP 
20 0 OR OF 
ai 0 6 ’BRANCH’ 
22 0 22 ‘SALESPERSON’ 
23 0 35 'CUSTOMER’ 
240 46 ’SALES’ 
25 0 H 2 ip 
26 0 OR OF 
27 0 4 'NO’ 
28 0 149 ‘’NO’ 
29 0 32 7NO’ 
30 0 46 "AMOUNT’ 
31 0 Di 04 
32 0 BRANCHZ 4 
33 °0 SLSPERZ 16 
34 0 CUSTNOZ 30 
35 0 SLSAMTi 45 
36 0 T 2 L4 
37 0 CUSTOTIB 45 
38 0 46 7x! 
39 0 T 12 L2 
40 0 42 "TOTAL SALESPERSON’ 
41 0 SLSPERZ 45 
42 0 SPTOT 1B 54 
430 56 He’ 
44 0 T 3 L3 
45 0 46 “TOTAL BRANCH NO’ 
46 0 BRANCHZ 49 
47 0 BRTOT 1B 64 
48 0 65 ' xxx’ 
439 0 T ft LR 
50 0 46 "FINAL TOTAL’ 
51 0 FINTOTi 59 ’$’ 
52 0 64 'xeKK’ 


2K-4391-85 


7-10 Using Indicators 


In the preceding example: 


Lines 5 through. 7 assign three control-level indicators, one each 

to three different control fields. The specification associates the 
highest control-level indicator (L3) to the most significant input 
field, BRANCH. The specification associates the next highest control- 
level indicator to SLSPER and the lowest control-level indicator to 
CUSTNO. | 


If the value of BRANCH changes from the previous record, indicator 
L3 is set on, which automatically sets on indicators L2 and L1. These 
three indicators can be used to condition calculation and output 
operations. 

In line 10, when indicator L1 is on, VAX RPG II adds the amount of 
the customer sale to the total sales for a particular salesperson. In 
line 11, when indicator L2 is on, VAX RPG II adds the total sales for 
the salesperson to the total sales for each branch. In line 12, when 
indicator L3 is on, VAX RPG II adds the total sales for each branch to 
compute the final total. 

Line 36 causes VAX RPG II to output the total sales for each customer 
number when indicator L1 is on. 

Line 39 causes VAX RPG II to output the total sales for each salesper- 
son when indicator L2 is on. 


Line 44 causes VAX RPG II to output total sales for each branch when 
indicator L3 is on. 


Using Indicators 7-11 


You can assign the same control-level indicator to more than one control 
field. These fields are called split-control fields. The following example 
shows how to use split-control fields: 


Sequence (AA-ZZ, 01-99) 
| Number (41-N) 





| [Optional/External (QU) Decimal positions 
| |iRecord identifying indicator | Control level 
1 tl | | Match field 
1 Jtl + Identifying codes + Format | | | Fld rec rel 
File rll | 1 | (PB) Field I | | 
name Pill C C Ci IField tIname | | | Field 
| 1 tlt t Z Z ZI tlocation!| | | | indicatrs 
Il | |11 Pos NDcPos NDcPos NDc IFr To II fi l+-0 
0 
re oe ee ee ee eT) HEH HHH oa, 
5 I 4 20BRANCHL1 
6 I 3  40SLSPERL1 
rae | 5  SOCUSTNOL 
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In this example, the fields BRANCH, SLSPER, and CUSTNO combine to 
form the control field. When VAX RPG II compares the data in these fields 
with the same fields in a previous record, indicator L1 is set on when the 
data changes. 


7.1.5 Overflow Indicators 


When the printer reaches the overflow line that signals the end of the 
page, VAX RPG II sets on the overflow indicator assigned to that printer 
output file. (See Chapter 9 for information on printer output files.) 


You define overflow indicators OA, OB, OC, OD, OE, OF, OG, and OV in 
columns 33 and 34 of the File Description specification. 
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In the following example, after reaching the overflow line, VAX RPG II 
sets on the overflow indicator OF. Then, the printer moves to the top of 
the next page and outputs the heading lines. 





Type (HDTE) Edit codes , ONOCR - 
Fetch ofl / Rel (FR) |X  — weeeeeeeerenn 
| 1Space | Y date edit YYiAadJ 
Ill Skip | Z zero suppress Y N 2 B K 
Wit | N Y 3 CL 
tt Indicators IBlank-after (B) N N 4 D M 
File Hi do Field !1End position 
name Hdd | name Ill Format (PB) 
| Hd | | 1 | 
0! L1BAB A NxxNxxNxx | Vl I+ Constant or edit word + 
i) | 4 | 2 | 3 | 4 | 5 6 | 7 | 
12345678901234567890123456 7890123456 7890123456 7890123456789012345678901234567890 
HH HHRRH H ¥ % HEH-—-—-HE copes 
14 OSLSREP H 201 OF 
i5 0 UDATE Y 9 
16 0 25 ‘SALES REPORT’ 
17 0 38 PAGE’ 
18 0 PAGE 43 
2K-4393-85 


See Chapter 9 for a full description of the overflow routine and overflow 
indicators. | 


7.1.6 K Indicators 


K indicators (KA through KZ and KO through K9) can be used to condition 
calculations, output records, and output fields. They can also be used as 
resulting indicators. K indicators are set on or off if a WORKSTN file is 
used. WORKSTN files are used when you want to interact with your VAX 
RPG II program at a terminal screen. See Chapter 6 for details. 


In the following program, a K indicator is set on and is displayed when 
its associated cursor control key is typed. CTRL/Z is pressed to end the 
program. Note that this use of K Indicators does not require a WORKSTN 
file. 
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0 | 1 | 2 
1234567890123456 7890123456789 





| 3 | 4 i 4) | i) | 7 
0123456 7890123456 7890123456 7890123456 7890123456 7890 





Fat 

Fx File: READ_CURSOR.RPG 

Fx 

F# This RPG II program demonstrates the use of the RTL routine 

F% SMG$READ_KEYSTROKE to read a keystroke from the terminal. 

Fx 

Fx The program takes input from the terminal until CTRL/Z is typed. 
Fx If any of the four cursor positioning keys is typed, a string 
Fx is displayed corresponding to the key. 
Fx 

Fx 
Fx 
F% $ RPG READ_CURSOR 
Fx $ CREATE SMGDEF.MAR 


Build this program using the following commands: 


Fx . TITLE SMGDEF - Define SMG$ constants 
Fx Ident /1-000/ 3 

Fx $SMGDEF GLOBAL 

FR 


» END 
Fx $ MACRO SMGDEF 
Fx $ LINK READ_CURSOR, SMGDEF 
FR-- 
FITY DOU 5 TTY 
CALL REAKEY 


€ 
Cx External definitions for SMG routines. 
C 


CREKB EXTRN’ SMG$CREATE..VIRTUAL_KEYBOARD’ 
C DELEB EXTRN’ SMG$DELETE.VIRTUAL_KEYBOARD’ 
Cc REAKEY EXTRN’ SMG$READ_KEYSTROKE’ 


Cx External definitions for SMG terminators. 


Cc a EXTRN’ SMG$K_TRM_UP’ 

Cc T_DOWN EXTRN’ SMG$K_TRM_DOWN’ 

C T_LEFT EXTRN’SMG$K_TRM_LEFT’ 

C T_RIGHT EXTRN’SMG$K_TRM_RIGHT’ 

Cc T_CTRLZ = EXTRN’SMG$K_TRM_CTRLZ’ 

Cx Create the virtual keyboard. 

C N99 CALL CREKB 

C PARM KB_ID 90 WL 

c SETON 99 

Cx Read a keystroke, 

Cc CALL REAKEY 

Cc PARM KB.ID 90 RL 

¢ PARM T.CODE 50 WW 

C* Turn on an indicator if a cursor positioning key was typed. 
C T_CODE COMP T_UP KA 
C T_CODE COMP T_DOWN KB 
¢ T_CODE COMP T_LEFT KC 
C T_CODE COMP T_RIGHT KD 
C* Turn on LR to quit if CTRL/Z was typed. 

¢ T-CODE COMP T_CTRLZ LR 
C# Display a message if a cursor positioning key was typed. 
Cc OKA UP’ DSPLYTTY 

CC KB "DOWN’ DSPLYTTY 

Cc KC "LEFT? DSPLYTTY 

Cc KD ’RIGHT’ © DSPLYTTY 


Cc Delete the virtual 
CLR 
CLR 


keyboard. 
CALL DELKB 
PARM 


KB_ID 90 RL 
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7.2 Internally Defined Indicators 


There are some indicators that you do not need to define; VAX RPG II 
defines them for you. This section describes internally defined indicators 
and explains how to use them. 


7.2.1 First-Page Indicator 


When you specify a first-page (1P) indicator, it is set on at the start of the 
program and set off after detail-time output but before the first record is 
read. Therefore, you can use the 1P indicator to condition these heading 
lines you want printed before VAX RPG II processes the first record. 


You specify the 1P indicator, which is always represented by 1P, in 
columns 24 and 25, 27 and 28, or 30 and 31 of the Output specification. 
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File 
name 


Ol 





*#% 


The following example shows how to use the 1P indicator to print a 
header on the first page of a report: 


Type (HDTE) Edit codes , ONOCR - 
Fetch ofl / Rel (FR) |X ween nnenn= 
| |Space | Y date edit YYiuiAadJ 
I}! Skip | Z zero suppress Y N 2 B K 
Itt | | NY 3 CL 
I}! | Indicators IBlank-after (B) N N 4 D M 
Hb de Field J1End position 

oe | name lil Format (PB) 

| | tl 

11B It I+ Constant or edit word + 
1 


HEKHK % % ¥% RRR——-— KE eeaen 


OQOUTPUT H 204 1P 


0 


ooonec0cecao0q 


OR OF 
UDATE Y 8 
43 'SALES REPORT’ 
PAGE 72 
67 ’PAGE’ 
H 22 1P 
OR OF 
5 ’ITEM’ 
23 ‘DESCRIPTION’ 
44 ‘SALES’ 
56 ‘COST’ 
72 ’PROFIT’ 
ZK-4385-85 
The following heading lines are printed on the first page: 
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 
12345678901234567890123466789012345678901234567890123456789012345678901234567890 
5/19/83 SALES REPORT PAGE 1 
ITEM DESCRIPTION SALES COST PROFIT 


You can use the 1P indicator to condition only detail or heading output 
lines. If you have a detail or heading output line conditioned by no 
indicators or all negative indicators, use a negative 1P (N1P) indicator to 
prevent this line from being output on the first cycle before the first record 
is read. 
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7.2.2 Last-Record Indicator 





Like the first cycle in a VAX RPG II program, the last cycle differs from 

all other program cycles. After VAX RPG II processes the last record in all — 
primary and secondary files for which you specified processing until the 
end-of-file, the last-record (LR) indicator is set on, along with all the other 
control-level indicators you specified. The LR indicator causes VAX RPG 

II to perform all total-time calculations and output operations conditioned 
by any control-level indicators and by the LR indicator. 


The LR indicator is always represented by LR, as shown in the following 
example: 


fess " Format (PB) 
| 
. | 

3 


| 
| i+ Constant or edit word + 
| 4 | s) | 6 | 7 | 


Type (HDTE) Edit codes , ONOCR - 
IFetch ofl / Rel (FR) | X a em 
| |Space | Y date edit YY iad 
l1t Skip | Z zero suppress Y N 2 B K 
Hl | NY Se Gs te 
111 | = Indicators IBlank-after (B) N N 4 D M 
fe | Field [lEnd position 

Hil | 

11B 

1 





| é 
1234567890123456789012345678901234567890123456 7890123456 7890123456 78901234567890 





HEX——-— HK ae 


30 ’TOTALS’ 
TSALESi 41 ’$’ 
TCOST 1 857 ’$’ 
TPROFIi 72 ’$’ 
ZK-4384-85 


The following information is printed only after processing the last record: 


0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 
TOTALS $564.30 $425.00 $139.30 


If your program does not contain a primary input file, you must set on the 
LR indicator to end the execution of the program. If your program sets 
on the LR indicator, VAX RPG II automatically sets on all control-level 
indicators just before total-time calculations. If the LR indicator is set on 
during total-time calculations, VAX RPG II does not automatically set on 
all control-level indicators. 
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7.2.3 Matching-Record Indicator 


When you use more than one primary and secondary file, VAX RPG II 
multifile logic supplies you with a method of selecting the next record to 
process. You can designate one or more fields in each record to be the 
matching fields (columns 61 and 62 of the Input specification). When the 
fields from a primary file and one or more of the secondary files match, 
the matching-record (MR) indicator is set on. The MR indicator remains 
set on while processing the records from the primary and secondary 
files that match. See Chapter 8 for a complete discussion of mulltifile 
processing. 


At the beginning of detail time, the MR indicator is set on or off, as de- 
termined by the matching status of the record to be processed. Therefore, 
at total time, the MR indicator reflects the matching status of the previous 
record with the record to be processed. 


7.2.4 External Indicators 


You can use external indicators to condition any operation in your pro- 
gram. External indicators, which are always represented by U1 through 
U8, can also appear in columns 71 and 72 of the File Description spec- 
ification and in columns 54 through 59 of the Calculation specification. 
External indicators can also be used as resulting indicators. 


To use the external indicator, you must also assign the logical name 
RPG$EXT_INDS to an external indicator using the DEFINE or ASSIGN 
command, as shown in the following example: 


$ DEFINE RPG$EXT_INDS "external-indicator-list" 


An external indicator is set on by specifying it in the external-indicator list. 
An external indicator is set off by not specifying it in the external-indicator 
list. 


The following example sets on external indicators U1, U5, and U4 and sets 
off external indicators U2, U3, U6, U7, and U8: 


$ DEFINE RPG$EXT_INDS "154" 


When you turn external indicators on or off in a program, the 
RPG$EXT_INDS is updated automatically for possible subsequent use by 
another program. 
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When you use an external indicator to condition a file, the file is opened 
only when the external indicator is set on. If the external indicator is set 
off, input files being processed sequentially are treated as if the end-of-file 
were reached. Use the same external indicator as a conditioning indicator 
to control calculation and output operations for those files being processed 
by methods other than sequential processing. Otherwise, a run-time error 
will occur when you attempt input or output operations on a file that was 
not opened because the external indicator was set off. 


7.2.5 Halt Indicators 


File 
name 


I] 





H¥ 


You can use halt indicators H1 through H9 as record-identifying indi- 
cators, field indicators, or resulting indicators to stop a program when a 
specific condition occurs. 


When you use a halt indicator as a record-identifying indicator, a specific 
type of record causes the halt. 


In the following example, a halt indicator is used as a record-identifying 
indicator, causing the program to check the character in position 80 of 
records read from the input file FILEIN. If the eightieth character is not an 
S, the halt indicator H1 is set on and the program will halt execution. A 
run-time message will/then be displayed saying that this indicator is set 
on. 


Sequence (AA-ZZ, 01-99) 

| Number (1-N) 

| lOptional/External (QU) Decimal positions 

| |lRecord identifying indicator | Control level 

Pull | | Match field 

| tll + Identifying codes + Format | | | Fld ree rel 

1 tli 1 | (PB) [Field | 1 | 

1 ttt ¢ ¢C Cl IField Iname | 1 | Field 

1 | Z Z Z| llocation| | | | | indicatrs 
tI lil 


+ - 0 


Pos NDcPos NDcPos NDc IFr To II 
2 | 3 | 


H FRR R--- ¥--- ¥--- RR ——R-——HRE Re HR RER LL, 


IFILEIN AA Hi 80NCS 
I 


I 


02 80 CS 
4 10 FIELD4 
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When a halt indicator is used as a field indicator, a halt occurs because of 
erroneous input data. 
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The following program uses a halt indicator as a field indicator. When a 
record is read from the input file FILEIN, FIELD1 is checked for a negative 
value. If FIELD1 contains a negative value, the indicator H2 is set on. 
After this record has been processed, the program will halt. 

| 1 | | 





| 3 | 4 | 4) | ) | 7 
eee 


He + % % H--HRE HR H 


IFILEIN AA Of 
I 4 SOFTELDA H2 
C NH2 SQRT FIELDi FDL2 95 


ZK-4382-85 


When a halt indicator is used as a resulting indicator, a halt occurs when 


calculations produce erroneous results during either detail time or total 
time. 


In the following example, a halt indicator is used as a resulting indicator. 
If the field FIELD1 is equal to zero, the indicator H4 is set on. After the 
current record is processed, the program halts. 


Field length 
1 Decimal positions 


Control level 
l 


lHalf adjust (H) 





| 
| Indicators Operation 1 oil 
| | 1} |lResulting 
1 | Factor | Factor Result! llindicators 
1 | 1 | 2 field | Il+- 90 . 
Cl NxxNxxNxx | | | | 1 tl> < = +- Comments --+ 
| | | 2 | 3 | 4 4) 3) | 7 | 
SELECT SLE TLC Le 
¥¥ % % % # H--HEX HH % 
C FIELD! SUB 59.0 FIELD{ H4 
C NH4 FIELD2 DIV. FIELD4 FIELD1 


ZK-438 1-85 


When a halt indicator is set on, a halt does not occur immediately. Before 


the program halts, it completes the current cycle and processes the record 
that caused the error condition. 


If any halt indicators are on after detail-time output, a run-time error 
occurs. 
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Halt indicators can also be used as field-record-relation indicators and 

to condition calculation and output operations. See Chapter 15 for more 
information on using halt indicators as field-record-relation indicators. If 
you are converting from another RPG II implementation, you might find 
an incompatibility with the halt indicators H1 through H9. For example, 
when IBM or Honeywell RPG II encounters a halt indicator, the operator 
is prompted to respond to a continue message. This allows the program 
to continue to execute. When VAX RPG II encounters a halt indicator, 
the program stops executing. The following code can be added to your 
program as a workaround. This will prompt the operator and provide the 
option of continuing: 


F* File spec for the screen display 
FITYFILE D F 81 TTY 


C* First time only 

C* 

Cc N99 MOVEL'continue'PROMPT 10 

Cc N99 MOVE '? '' PROMPT 

Cx 

C* If halt indicator is on prompt for continue 
C* 

Cc Hi PROMPT DSPLYTTYFILE ANSWR i 


C* Test operator's response if YES then setof HALT indicator 
C* to continue and blank out answer , 


C* 

Cc #H1 ANSWR COMP 'Y' 98 
Cc. 98 SETOF H198 
C MOVE ' ' ANSWR 


The testing of the halt indicator should come after the detail-time calcula- 
tions. 


If this workaround is running from within a command procedure, 
SYS$INPUT needs to be redefined to your terminal. For example: 


$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND 
$ RUN SAMPLE 


For more information on running the program from a command procedure, 
see the Guide to Using DCL and Command Procedures on VAX/VMS. 


Using Indicators 7-21 


7.3 Using Indicators as Fields 


The #IN, *IN,n, and *INxx are special words that allow you to use prede- 
fined indicators in your program. Sections 7.3.1 and 7.3.2 describe each 
type of special word. 


7.3.1 *IN and «IN,n 


The special word *IN is a predefined array with 99 one-position character 
elements. The elements in this array represent indicators 01 through 

99. Use *IN,n, where n is the array index, to reference an indicator. For 
example, *IN,54 refers to indicator 54. 


The elements in this array can assume only two character values—1 and 0. 
If you reference an indicator using *IN,n and the contents of the element 
are 0, the indicator is set off. If the contents of the element are 1, the 
indicator is set on. 


You can use either the array or the array element to reference an indicator 
anywhere any other one-character array or array element can be used. » 
You cannot, however, specify the entire array *IN as the Result field of 

a PARM operation. To prevent unpredictable results when modifying an 
element in *IN, assign the character literal 0 or 1 to *IN. 


In the following example, the program tests whether the setting for 
indicator 15 is equal to the setting for indicator 20. In the next line, 
indicator 20 is set on. Using the MOVE operation to transfer 1 to *IN,20 
produces the same result as using the SETON operation code to set on 
indicator 20. 


Field length 
Control level 1 Decimal positions 
| IHalf adjust (H) 





| 
| Indicators Operation 1 4 
1 | | | IlResulting 
I | Factor | Factor Result! | {indicators 
i | i | 2 field | Il+ - 0 . 
1 NxXxXNXXNXXI a | TL oLl> < = +- Comments --+ 
0) | 4 | 2 | 4 | 5 | 6 | 7 i 
ae easL TA eA lea 23456 7890123456 7890123456 7890123456 7890123456 78901234567890 
HR % % % ¥ H--#RE HK % 
C XIN, 20 COMP *IN,15 99 


C MOVE ’1’ *IN, 20 
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7.3.2 #INxx 


The special word *INxx is a predefined one-position character field where 
xx represents any indicator except the first-page (1P), overflow, or external 
indicators. Like *IN, it can contain only the character 0 or 1. 


You can use *INxx anywhere any other one-character field can be used, 
except as the result field of a PARM operation. 


In the following example, the value of the MR indicator is compared to the 
value of M. If they are the same, indicator 99 is set on. The MR indicator 
is represented as *INMR. 


a ee es | 


4 a | 3 | 4 
123456789012345678901234567890123456 78901 234567890123456789012345678901 234567890 





01 

4 20 TEXT 

19 20 MATCH Mi 
02 

2 21 TEXT 

20 21 MATCH Mi 
*INMR COMP M 99 


ZK-4379-85 
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Chapter 8 
Using Files 


A file is a collection of information that is organized into groups or 
sections called records. Each record consists of one or more blocks of 
characters or numbers called fields. 


This chapter explains the VAX RPG II file organizations and record 
operations that are implemented through VAX Record Management 
Services (RMS). For additional information on file organization and file 
and record operations, see the VAX Record Management Services Reference 
Manual and the Guide to VAX/VMS Disk and Magnetic Tape Operations. 


8.1 File Characteristics 


Files are created, modified, and processed according to their respective 
characteristics, which are chosen to make the most efficient use of both 
system resources and the data in the files. Significant characteristics of 
files used in VAX RPG II programs are the file type, designation, and mode. 
of processing. | 


The file type used in VAX RPG II programs determines how the records in 
the files are processed. See Chapter 15 for information on file type. The 
file types include: | 

e Input (I) 

e Output (O) 

e Update (U) 

e Display (D) 

e Combined (C) 


Using Files 8-1 


See Chapter 6 for detailed information on Combined (WORKSTN) files. 


File designations define the order in which VAX RPG II processes files. 
See Chapter 15 for information on file designations. The file designations 
include: . 

e =Primary (P) 

¢ Secondary (S) 

e Record-address (R) 

e Chained (C) 

¢ Preexecution-time table or array (T), (A) 

e Demand (D) 

e Full-procedural (F) 


8.2 File Names 
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Columns 7 through 14 (File name) of the File Description specification 
define the file name. VAX RPG II uses the entry in columns 7 through 14 
(File name) and the entry in columns 47 through 52 (Symbolic device) to 
associate the file name with the VAX/VMS file specification. The default 
VAX RPG II file type is DAT. 


You can use a logical name for the entry in columns 47 through 52 
(Symbolic device), and then assign a VAX/VMS file specification to the 
logical name. If you assign a full file specification to the logical name, 
VAX RPG II ignores the entry in columns 7 through 14 when determining 
the file specification. If you do not assign the file-name part of the file 
specification to the logical name, VAX RPG II uses the entry in columns 7 
through 14 when determining the file specification. If you do not assign a 
file type to the logical name, VAX RPG II uses DAT. 


If you do not specify an entry in columns 47 through 52, you can use a 
logical name as the entry in columns 7 through 14 for the VAX/VMS file 
specification. If you do not specify a logical name as the entry in columns 
7 through 14, the file specification will consist of the file name in columns 
7 through 14 and the file type DAT. 


The entry in columns 7 through 14 is used as the VAX Run-Time Library 
default file name string. The entry in columns 47 through 52 (symbolic 
device) is used as the VAX/VMS Run-Time Library file name string. See 
the VAX Record Management Services Reference Manual for information 
about file-name strings and default file-name strings. 


8.3 Record Formats 


The records in a file can all be the same length (fixed) or of different 
lengths (variable). Variable-length records often use disk storage space 
more efficiently. The characteristics and requirements of individual appli- 
cations should be carefully considered when you decide whether to use 
fixed-length or variable-length records. 


8.4 File Types 
You can use files in four ways: 


e As input to a VAX RPG II program 
'@ As output from a VAX RPG II program 
e As an update file in which the records are changed by the program 


e To interact with the terminal screen using the VAX Forms 
Management System (VAX FMS) (see Chapter 6 for details) 


8.5 File Organizations 


The organization of a file determines how the records in it are arranged. 
VAX RPG II allows three different file organizations: 

e Sequential 

e Direct 

e Indexed 


Sections 8.5.1 through 8.5.3 describe these file organizations. 
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8.5.1 Sequential Organization 


Sequential file organization is available on all types of devices. Sequential 
files contain records in the order that they were written. The first logical 
record in the file is always in the first physical record position, the second 
logical record in the file is always in the second physical record position, 
and so on. If you need to access the fourth logical record, you can find it 
between the third and fifth physical records, as shown in Figure 8-1. 


Figure 8-1: Sequential File Organization 


fs fe fede dsl 


fourth record 
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You can retrieve records from a sequential file either sequentially, by 
reading through the entire file from beginning to end, or randomly, by _ 
using relative record numbers or an ADDROUT file. 


8.5.2 Direct Organization 
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Direct file organization is available on disk devices only. The VAX/VMS 
Run-Time Library handles VAX RPG II direct files as files with relative 
file organization. A direct file consists of a series of fixed-length positions 
(or cells) that are numbered consecutively from 1 to n. This number is 
the relative record number; it indicates the record’s position relative to the 
beginning of the file. (The relative record number of the first cell is always 
1.) Each record you write is assigned to a specific cell within the file. For 
example, you can assign the second record to the fourth cell; its relative 
record number would be 4. This assignment can result in empty cells; 
therefore, you must specify a record’s relative record number to access it. 
Figure 8-2 shows that cell numbers 2 and 5 are empty cells. 


Figure 8-2: Direct File Organization 


cell no. ——» 1 2 3 4 5 6 





empty cell — empty cell 
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Direct files can be accessed sequentially or randomly by using the CHAIN 
operation code (see Section 16.7.1 for information on the CHAIN op- 
eration code) or by using an ADDROUT file. When you access a direct 
file sequentially, empty cells are skipped. When you access a direct file 
randomly using the CHAIN operation, the indicator specified in columns 
54 and 55 of the Calculation specification will be set on for an empty cell. 


8.5.3 Indexed Organization 


Indexed file organization is available on disk devices only. Each record in 
an indexed file contains an index key value, as shown in Figure 8-3. 


Figure 8-3: Indexed File Organization 


index key value 





record — 
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An index key value is a field within each record that is defined by its 
relative location within the record and by its length. The index key value 
is the primary means of locating records within the file. For example, 
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you could use an employee’s badge number as the index key value for 
an employee record. The index key value in Figure 8-4 is the first six 
characters in the record, or 768979. 


Figure 8-4: Index Key Value 


key 


768979Henry Alberts 


record 
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You can retrieve a record from an indexed file by specifying its index 

key value. In fact, you can retrieve records in an indexed file either _ 
sequentially or randomly by using index key values, or randomly by using 
an ADDROUT file. 


Another way to access records from an indexed file is sequentially within 
limits. See Section 8.6.3 for more information on this method of accessing 
records from indexed files. 


8.6 File Access Methods 


There are several ways you can access the records in a file, depending on 
its organization. Table 8-1 lists file organizations and the methods you 
can use to retrieve records. 
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Table 8—1: File Access Methods 


File Designation Organization Access Method 

Primary Sequential Sequentially 

Secondary Randomly by ADDROUT file! 

Demand Direct Sequentially 

Full-procedural Direct Randomly by relative record number 
Indexed Sequentially 


Sequentially by key 
Sequentially within limits 
Randomly by ADDROUT file! 


Chained Sequential Randomly by relative record 
number” 
Indexed Randomly by key 


You cannot process demand or full-procedural files using an ADDROUT file. 


2You can access the records in a sequential file randomly by relative record number if the records are 
fixed-length and the file resides on disk. 


Although you cannot change the organization of a file after you have 
created it, you can change the file access method each time you use the 
file. The method you use depends on how many records your file contains 
and how often you need to access a record. Use the following guidelines 
in selecting a file organization and access method: 


e If you always process all the records in a file from beginning to end (as 
in a payroll application), use a sequential file and access the records 
sequentially. 


e If you need to access some or all records under changing or unpre- 
dictable conditions (as in a transaction processing system), use an 
indexed or direct file and access the records randomly. 


Sections 8.6.1 through 8.6.5 describe each file access method and provide 
programming guidelines for each. 
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8.6.1 Sequential Access 


When you access a file sequentially, each input operation retrieves the 
next record in the file, regardless of the file organization, until either the 
end-of-file is reached or the program terminates. For an indexed file, 
records are retrieved in the order of the primary keys. 


To specify sequential access for a file, you must make the following entries 
in its File Description specification: 


¢ Column 15 (file type)—specify I or U to indicate whether the file is to 
be opened for input or for update. 


e¢ Column 16 (file designation)—specify P, S, D, or F to indicate whether 
the input file is primary, secondary, demand, or full-procedural. 

e Column 19 (record format)—specify F or V to describe the record 
format. 


¢ Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 


The following example specifies the name of a file, INPUT, designated as 
an input primary file with fixed-length records and a record length of 60 





bytes: 
Mode (LR) 
IKey length 
Type (IOUDC) I! Record address type (APIB) Addtn( AU) 
IDes(PSRCTDF)11! lOrganization (IT,1-9) [Expand 
I1EOF ¢E) 11 [lOverflow indicator Continue (K) [1Shr(SR) 
— TitSeq (AD) Tl TET Key location lOpt = =Entry I1l Rewnd 
File P11tFmt (FY) TI til t | Extension (EL) II | Hii | 
nane HIVEIBIK Rec TI G1t 1 = [Device Symb Tape Core II! IFile 
| lltttlen len Tl tlt 1 = leode dev label index III Icond 
FI ee | | | Hil 
0) 1 | 2 | 
) 
ae HERKKE--—H-——HRR-KRH H-—— RE * Pe eee HEX HK, 


FINPUT IP F 60 DISK 
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8.6.2 Sequential Access by Key 


You can process only indexed primary, secondary, demand, and full- 
procedural files sequentially by key. VAX RMS reads records in ascending 
key sequence until it reaches the end of the file or until the program 
terminates. 


To specify sequential access by key for a file, you must make the following 
entries in its File Description specification: 


Column 15 (file type)—specify I or U to indicate whether the file is to 
be opened for input or for update. 


Column 16 (file designation)—specify P, S, D, or F to indicate whether 
the input file is primary, secondary, demand, or full-procedural. 
Column 19 (record format)—specify F or V to describe the record 
format. 

Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 
Columns 29 and 30 (key length)—specify the length of the key field. 
For binary, use 2 for word and 4 for longword. 


Column 31 (record address type)—specify either A, P, or B to indicate 
that the index keys are in character (A), packed decimal (P), or binary 
(B) data format. 


Column 32 (file aaa a I to indicate that the file is an 
indexed file. 


Columns 35 through 38 (key location) —specify the starting character 
position of the key field. 
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The following example shows how to specify a primary input file, INPUT, 
with fixed-length records 60 bytes long. The file organization is indexed 
with its index keys in packed decimal data format. 





Mode (LR) 
IKey length 
Type (IOUDC) |1 Record address type (APIB) Addtn( AU) 
IDes(PSRCTDF)11 lOrganization (IT, 1-9) [Expand 
TIEOF (ED 11 |]Overflow indicator Continue (K) | 1Shr(SR) 
111Seq (AD) Il Ill Key location lOpt Entry fll Rewnd 
File TEtdFmt (FY) TI Tt! | | Extension (EL) II | Hi 
name ITTIBIK Rec Tl ttt | = Device Symb Tape Core JI! IFile 
| Itl}tlen len Tl tt) |) = Ieode dev label index III Icond 
FI ee ee | | | Hit Wt 
0 1 2 | 3 | 4 | a) | 6 | 7 | 
123456 7890123456 7890123456 7890123456 7890125456 7890123456 789012345678901234567890 
Ty HERHEK——~8——— RH HEE H--— HK % Rideau ¥----- TTS Le 
FINPUT IP F 60 3PI 1 DISK 
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8.6.3 Sequential Access Within Limits 


You can process indexed files sequentially within limits by creating a 
record-limits file that specifies a range of index keys in each record. 


In Figure 8-5, the first record in the record-limits file causes VAX RPG II 
to retrieve those records whose keys are greater than or equal to the low 
key (C) and less than or equal to the high key (E). When the program 
reaches a record with a key value greater than E or reaches end-of-file, 
it reads the next record from the record-limits file to get a new high and 
low range. The second record in the record-limits file causes the program 
to retrieve those records whose keys are greater than or equal to the low 
key (E) and less than or equal to the high key (G). The indexed file is 
processed until it reaches the end of the record-limits file or the program 
terminates. 
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Figure 8-5: Sequential File Access Within Limits 
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e In the record-limits file, you can specify only one set of limits for a 
record. 


¢ The record length must be at least twice the length of the record key. 


e The low key must begin in character position 1, and the high key 
must immediately follow the low key. 


¢ The length of the high and low keys must be the same and must be 
equal to the length of the key field in the file to be processed. 


e Numeric keys can contain leading zeros. 
e Alphanumeric keys can contain blanks. 
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To access a file sequentially within limits, you must make the following 
entries in its File Description specification: 


¢ Column 15 (file type)—specify I or U to indicate whether the file is to 
be opened for input or for update. 


¢ Column 16 (file designation)—specify P, S, D, or F to friaieate whether 
the input file is primary, secondary, demand, or full-procedural. 


© Column 19 (record format)—specify F or V to describe the record 
format. 


e¢ Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 


© Column 28 (access mode)—specify L to indicate that the indexed file 
is to be processed sequentially within limits. 


¢ Columns 29 and 30 (key length)—specify the length of the key field. 


¢ Column 31 (record address type)—specify either A, B, or P to indicate 
that the index keys are in character (A), packed decimal (P), or binary 
(B) data format. 


e Column 32 (file organization)—specify I to indicate that the file is an 
indexed file. 


e¢ Columns 35 through 38 (key location)—specify the starting character 
position of the key field. 


The following example shows how to specify an input secondary file, 
INPUT, with fixed-length records 60 bytes long. This file is to be pro- 
cessed sequentially within limits. The file organization is indexed, the key 
field is three bytes long beginning in character position 1, and the keys are 
in character format. 





Mode (LR) 
Key length 
Type (IOUDC) || Record address type (APIB) Addtn(AU) 
IDes(PSRCTDF) I! lOrganization (IT, 1-9) [Expand 
FIEOF (E) 11 |lOverflow indicator Continue (K) [iShr(SR) 
11}1Seq (AD) Jl TI Key location Opt Entry Il Rewnd 
File P1ViFmt (FY) JI III | | Extension (EL) II | 11 4 
name TITTIBIK Rec JI tll | Device Symb Tape Core III IFile 
| Hlllflen len Tl dtl |} = teode dev label index III Icond 
Fl ee ee ee | | | tout, 
4 | 2 | 3 | 4 | a) | 5) | 7 | 
1234567890123456 78901235456 7890123456 7890123456 7890123456 7890123456 7890123456 7890 
#% HHHKER--—H--—RR- REE H--— RE * ee HEX HH, 
FINPUT IS F 60L SAI 4 DISK 
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To access a file sequentially within limits, you must make the following 

entries for the record-limits file in its File Description specification: 

e Column 15 (file type)—specify I to indicate that the file is to be 
opened for input. 

e Column 16 (file designation)—specify R to indicate that the file named 
in columns 7 through 14 is a record-limits file. 

e¢ Column 19 (record format)—specify F or V to describe the record 
format. | 

¢ Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 

¢ Columns 29 and 30 (key length)—specify the length of the key field. 

e¢ Column 31 (record address type)—specify either A, P, or blank to 
indicate that the index keys are in character (A), packed decimal (P), or 


the same data format as the file being processed by the record-address 
file (blank). 


e Column 39 (extension)—specify E to cause the system to look for an | 
Extension specification. 


You must also make the following entries for the record-limits file in its 
Extension specification: 


¢ Columns 11 through 18 (from file name)—specify the name of the 
record-limits file. 


e¢ Columns 19 through 26 (to file name)—specify the name of the file to 
be processed by the record-limits file. 


The following example shows how to specify the File Description and 
Extension specifications for processing a file sequentially within limits: 


) | 1 i 2 | 3 | 4 | 4) | Ls) | rs | 


1234567890123456 7890123456 7890123456 7890123456 7890123456 7890123456 78901234567890 
FIDXAi2 IR F 6 3A EDISK 
FIDXIi2 IP F 60L 3AI 4 DISK 
E IDXAi2 IDXIi2 
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An indexed demand or full-procedural file can also be processed se- 
quentially within limits using the SETLL operation. See Chapter 16 for 
information on the SETLL operation code. 
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8.6.4 Random Access 


Accessing records randomly allows you to retrieve or write a record 
anywhere in the file. To do this, you must specify the record location 
using one of the following methods: 

e Relative record numbers 

e Keys . 

e An ADDROUT file 


The method you use depends on the organization of the file. Sections 
8.6.4.1 through 8.6.4.3 explain these methods. 


8.6.4.1 Random Access by Relative Record Number 
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You can randomly access records in sequential and direct files by specify- 
ing relative record numbers that identify records relative to the beginning 
of the file. For example, the relative record number for the fifth record is 
5. Accessing a sequential file using this method requires that the records 
be of fixed length and that the file reside on disk. 


To access a file randomly by relative record number, you must make the | 
following entries in its File Description specification: 


e¢ Column 15 (file type)—specify I or U to indicate whether the file is to 
be opened for input or for update. 

° Column 16 (file designation)—specify C or F to indicate whether the 
file named in columns 7 ous 14 is a chained or full-procedural 
file. 


¢ Column 19 (record format)—specify F or V to describe the record 
format. 


e Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 


¢ Column 28 (mode)—specify R to cause VAX RPG II to access the file 
randomly, using a relative record number. 


You must also make the following entries for the file in its Calculation 
specification: 


¢ Columns 18 through 27 (factor 1)—specify the relative record number 
of the record you want to retrieve. 





0 
12345 


l 
FRANIO7 
FRANO7A 
FRANO7B 
IRANIO7 
I 


I 
TRANO7A 


50 


RANO7A 


RANO7B 


Oaeoeeceaooe a aaAraiagagaas» sane 


e Columns 28 through 32 (operation code)—specify the CHAIN op- 
eration code. Use an indicator in columns 54 and 55 to signal an 
empty cell condition for a direct file. Otherwise, attempting to use the 
CHAIN operation code to randomly access an empty cell will cause a 


run-time error. 


¢ Columns 33 through 42 (factor 2)—specify the name of the file that 
contains the record you want to retrieve. 


The following example shows how to randomly access the direct file 
RANOZA by relative record number. The primary input file RANIO7 
provides the record numbers in the field ITEM#. 


i | 2 | 


3 | 4 | 5 | ) | 7 
678901234567890123456 7890123456 78901234567890123456 7890123456 78901254567890 


IP F . 43 
uc OF 10R 
Oo F 30 
AA O01 
AB 02 


ITEMH © CHAINRANO7A 
GOTO HANDLR 
1 ADD ACCESS 
SETON 
EXCPT 
SETOF 
HANDLR TAG 
SETON 
E 02 40 
RECH 


ACCESS 
VALUE 
H 22 iPN40 


D O1N40 
STORE 
ACCESS 
VALUE 





DISK 
DISK 
PRINTER 
1 11 STORE 
13 1301TEMH 
1 L0RECH 
3 BOACCESS 
7 10 VALUE 
50 
ACCESS 
40 
40 
LR 
1 
5 
10 


22 ‘STORE PURCHASES’ 


14 
20 
27 
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8.6.4.2 Random Access by Key 


You can randomly retrieve records from an indexed file by specifying their 
index keys. 
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To access a file randomly by key, you must make the following entries in 
its File Description specification: 


Column 15 (file type)—specify I or U to indicate whether the file is to 
be opened for input or for update. 

Column 16 (file designation)—specify C or F to indicate whether the 
file named in columns 7 through 14 is a chained or full-procedural 
file. 

Column 19 (record format)—specify F or V to describe the record 
format. 

Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 


Column 28 (mode)—specify R to tell VAX RPG II to access records 
randomly, using index key values. 


Columns 29 and 30 (key length)—specify the length of the key field. 


Column 31 (record address type)—specify either A or P to indicate 
that the index keys are in character (A) or packed decimal (P) data 
format. 


Column 32 (file organization)—specify I to indicate that the file is an 
indexed file. 


Columns 35 through 38 (key location)—specify the starting character 
position of the key field, 


You must also make the following entries for the file in its Calculation 
specification: 


Columns 18 through 27 (factor 1)—specify the index key of the record 
you want to retrieve. 


Columns 28 through 32 (operation code)—use the CHAIN operation 
code. The record you specify can be read from the file either during 
detail-time or total-time calculations. Specify an indicator in columns 
54 and 55 to signal a record-not-found condition. Otherwise, a 
record-not-found condition will cause a run-time error. 


Columns 33 through 42 (factor 2)—specify the name of the file to be 
processed. 


0 


The following example randomly accesses the indexed file GROCER 
using keys. The primary input file STORES provides the keys in the field 
ITEM#. 





I 
IGROCER 


oi 
ao 


REPORT 


oOooocan anne 


io No BOY des is hee Pe Le ee 
F 13 DISK 
IC F 10R 1AI 1 DISK 
0 F 30 PRINTER 
AA 04 
1 44 STORE 
13 130ITEMH 
AB 02 
| 1  40RECH 
3 50COUNT 
7 40 VALUE 
ITEMH © CHAINGROCER 50 
SETON LR 
H 22  — 4PN4O 
22 "STORE PURCHASES’ 
D O4N40 
STORE 14 
COUNT 20 
VALUE 27 
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8.6.4.3. Random Access by ADDROUT File 


Another way to process files is by using an ADDROUT file. You can use a 
record-limits file to process only indexed files. You can use an ADDROUT 
file to process sequential, direct, or indexed files. 


ADDROUT files are created by the VAX/VMS Sort/Merge Utility 
(SORT/MERGE) when you use the /PROCESS=ADDRESS qualifier. 
You specify a field or fields in the record by which SORT/MERGE sorts 
the records, as shown in Figure 8-6. 
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Figure 8-6: Random Access by ADDROUT File 


record 





field to sort 


ZK-1467-83 


SORT/MERGE sorts the records and places the disk addresses of the 
sorted records in an ADDROUT file, as shown in Figure 8-7. 
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Figure 8—7: An ADDROUT File 









000143 
948567 


~=e———— address of A 
~—a———. address of B 


762341 | ~—-7-— address of C 


098745 | ——— address of D 


ADDROUT file 
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The program reads the records (addresses) in the ADDROUT file sequen- 
tially. Each record in the ADDROUT file corresponds to a record in the 
original file. The addresses of the records are referred to as Record File 
Addresses (RFAs) by VAX RMS. For additional information on RFAs, see 
the VAX Record Management Services Reference Manual. 


To access a file using an ADDROUT file, you must make the following 
entries in the File Description specification of the file to be accessed: 


Column 15 (file type)—specify I or U to indicate whether the file is to 
be opened for input or for update. 


Column 16 (file designation)—specify P or S to indicate that the file 
named in columns 7 through 14 is primary or secondary. 


Column 19 (record format)—specify F or V to describe the record 
format. 


Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 


Column 28 (mode)—specify R to cause VAX RPG II to access records 
randomly. 


Columns 29 and 30 (key length)—specify the length of the key field if 
you plan to access an indexed file. 


Column 31 (record address type)—specify I to cause the program to 
access the file according to the ADDROUT file. 
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Column 32 (file organization)—specify 1 if you plan to access an 
indexed file. 

Columns 35 through 38 (key location)—specify the starting character 
position of the key field if you plan to access an indexed file. 


To access a file using an ADDROUT file, you must make the following 
entries for the ADDROUT file in its File Description specification: 


Column 15 (file type)—specify I to indicate that the file is to be open 
for input. 


Column 16 (file designation)—specify R to indicate that the file named 
in columns 7 through 14 is an ADDROUT file. 


Column 19 (record format)—specify F to describe the record format. 


Columns 24 through 27 (record length)—specify 6, because record 
addresses are always 6 bytes in length. 

Columns 29 and 30 (key length)—specify 6, because key addresses are 
always 6 bytes in length. 

Column 31 (record address type)—specify I to indicate that this is an 
ADDROUT file. | | 
Column 32 (file organization)—specify T to indicate an ADDROUT 
file. 

Column 39 (Extension)—specify E to cause VAX RPG II to look for an 
Extension specification. 


You must also make the following entries for the ADDROUT file in its 
Extension specification: 


Columns 11 through 18 (from file name)—specify the name of the 
ADDROUT file. - 


Columns 19 through 26 (to file name)—specify the name of the file to 
be processed by the ADDROUT file. 


The following example shows how to specify the ADDROUT file 
IDXA13 and how to specify the file IDXI13 which will be accessed by 
the ADDROUT file. 





0 | eee 2 | 3 | 4 | 5 | Ls) | vi I 
123456 7890123456 789012345678901234567890123456 7890123456 7890123456 7890123456 7890 
FIDXAi3 IR F 6 6IT EDISK 
FIDXIi3 IP F 60R 3II { DISK 
FIDXi3A OO F 80 OF PRINTER 


E IDXAI3 IDXI13 
IIDXI13 AA 02 


I 4 3 KEY 

I 4 412 TOWN 
I 13 14 STATE 
I 45 25 COUNTY 
I 26 30 ZIP 

I 31 S50CEN3O 
I 36 400CEN40 
I 41 450CEN50 
I 46 SOOCEN60 
I 51 550CEN70 
I 56 600CEN8O 
OIDX13A H 202 iP 

0 OR OF 

0 UDATE Y 10 

0 49 "NEW HAMPSHIRE TOWNS’ 
0 PAGE 77 

0 Di 02 

0 TOWN 13 

0 COUNTY 26 

0 STATE 30 

0 CEN80 Jo 38 

0 CEN70 J 46 

0 CEN60 J 54 

0 CEN5O J G2 

0 CEN40 J 70 

0 CEN3O J 78 
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8.6.5 Sequential Access and Random Access by Key 


A full-procedural file allows you to read a file both randomly and sequen- 
tially. If the full-procedural file is an indexed file, then you can read the 
file randomly by key using the CHAIN or SETLL operation, and you can 
read the file sequentially. 
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To specify an indexed full-procedural file, make the following entries for 
the file in its File Description specification: 


Columns 7 through 14 must contain the file name. 


Column 15 (file type)—specify I or U to indicate that the file is to be 
opened for input or for update. 


Column 16 (file designation)—specify F to indicate a full-procedural 
file. 


Column 19 (record format)—specify F or V to desta the record 
format. 


Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 


Column 28 (access mode)—specify L to indicate that the indexed file 
is to be processed sequentially within limits. 


Columns 29 and 30 (key length)—specify the length of the key field. 


Column 31 (record address type)—specify either A, B, or P to indicate 
that the index keys are in character (A), packed decimal (P), or binary 
(B) data format. 


Column 32 (file urgenization) —<epectty I to indicate that the file is an 
indexed file. 


Columns 40 through 43 (device code)—specify DISK. 


The following example specifies the full-procedural file FPFJ01 to be 
accessed by a CHAIN operation with the key specified in FPFIO1. The file 
FPFJ01 is then processed sequentially from that point on. 








0 1 é 3 | 4 | 7 6 | i | 
123456 7890123456 7890123456 789012345678901234567890123456789012345678901234567890 

FITY D F* 80 — TTY 

FFPFIO1 ID F 04 DISK 

FFPFJO1 IF V 47RO4AI 4 DISK 

FFPFOLA O VY 7 LPRINTER 

LFPFOiA = S5FL 500L . 

IFPFIOL 

I { 4 PARTNO 
IFPFJOL 

I { 4 PARTNO 
I 5 39 DESCR 

I 40 43 PRICE 

I 44 47 AMOUNT 
C READ FPFIO4 : 

¢ PARTNO CHAINFPF JO1 98 

C . EXCPT 

C 6398 "BAD’ DSPLYTTY 

C 98 GOTO END 

C LOOP TAG 

¢ READ FPFJO4 LR 
C NLR EXCPT 

C NLR GOTO LOOP 

C END TAG 

OFPFOLA H 201 iP 

0 32 "PARTS SUMMARY INVENTORY’ 
0 H 10 iP 

0 41 ’PART NO’ 

0 30 ‘DESCRIPTION’ 

0 H 00 iP . 

0 BOF ce toa : 

0 H Of iP 

0 Oy rene : 

0 E Of . 

0 PARTNO 9 

0 DESCR 47 
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8.7 Creating Files 


There are a variety of ways to create files with sequential, direct, and 
indexed organizations. Sections 8.7.1 through 8.7.3 describe how to create 
files using a VAX RPG II program. 


8.7.1 Creating Sequential Files 


You can create sequential files by writing consecutive records to an output 
file. After a sequential file is created, you can use it as an input file, an 
update file, or an output file with the ADD option. 


To create a sequential file, you must make the following entries in the File 

Description specification: 

e Column 15 (file type)—specify O to indicate the creation of an output 
file. 

¢ Column 19 (record format)—specify F or V to describe the record 
format. 


¢ Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 


The following example shows how to create the sequential file OUT60A: 





0 | 4 | 2 | 3 | 4 | 5 | ) | 7 | 





1234567890123456789012345678901234567890123456 7890123456 789012345678901234567890 
FOUTI2@4 IP F 24 DISK : -_ 
FOUT60A O F a4 DISK. 

IQUTI24 AA 

I 4 3 PN 

I 4 10 PNANE 
I 41 12 WHOUSE 
I 13 17 COLOR 
I 48 20 WEIGHT 
I . 21 24 QTY 
ODOUT60A D NiP 

0 PN 3 

0 PNAME 10 

0 4 '4' 

0 WHOUSE 12 

0 COLOR 17 

0 WEIGHT 20 

0 QTY 24 


ZK-4401-85 


8-24 Using Files 


8.7.2 Creating Direct Files 


You can create a direct file by specifying a chained output file. To do this, 
you must make the following entries in its File Description specification: 


¢ Column 15 (file type)—specify O to indicate the creation of an output 
file. . 


¢ Column 16 (file designation)—specify C to indicate that the file named 
in columns 7 through 14 is a chained file. 

e Column 19 (record format)—specify F or V to describe the record 
format. 

¢ Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 


¢ Column 28 (mode)—specify R to cause VAX RPG II to load a direct 
file. 


The following program shows how to create the direct file OUT60B with 
variable length records: 






0 | { li 2 l 3 l r Nl 5 | 6 i 7 Nl 
RL ECYEL USER, GCVELCUSER, GCYC USERS GUFCISERE SCVALISERT GVALUR ERE al YAS CURRY aU PEeCl0 
FOUTI24 IP F 24 DISK © 





FOUT60B OC V 24R DISK 

IQUTI24 AA 

I 1 3 PN 

I 4 10 PNAME 
I 41 12 WHOUSE 
I 43 17 COLOR 
I 18 20 WEIGHT 
I 21 24 QTY 

¢ COUNT ADD 1 COUNT 10 

¢ COUNT CHAINOUT60B 99 
OOUT60B D NAP 25 

0 PN 3 

0 PNAME 10 

0 4 °3’ 

0 WHOUSE {2 

0 COLOR 17 

0 WEIGHT 20 

0 QTY 24 
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8.7.3 Creating Indexed Files 
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You can create an indexed file either in unordered key sequence or in 
ordered key sequence. If you specify unordered, you can write records to 
an indexed file in any order, regardless of the key sequence. If you specify 
ordered, you must write records in the order of their key; the order must 
be ascending. After the file is created, VAX RMS sorts the index keys in 
ascending order, regardless of the order in which they were written. 


To create an indexed file in ordered sequence, you must make the follow- 
ing entries in its File Description specification: 


Column 15 (file type)—specify O to indicate the creation of an output 
file. 

Column 19 (record format)—specify F or V to describe the record 
format. 


Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 


Columns 29 and 30 (key length)—specify the length of the key field. 
For binary, use 2 for word length and 4 for longword length. 


Column 31 (record address type)—specify either A, P, or B to indicate 
that the index keys are in character (A), packed decimal (P), or binary 
(B) data format. 


Column 32 (file Seanics aan) aaah I to indicate an indexed file. 


Columns 35 through 38 (key location)—specify the starting character 
position of the key field. — 


The following program shows how to create an indexed file OUT60A with 
an alphanumeric key that is three bytes long. The key begins in character 
position 1 of each record. 


Cie fe aoe [cee ae pe eb Bo Cok eR 


123456789012345678901234567890123456 7890123456 789012345678901 23456 78901234567890 





FOUTI24 IP F 24 DISK 

FOUT60A O V 24 SAI 1 DISK 

IOUTI24 AA O1 

I 4 3 PN 

I 4 10 PNAME 
I 41 12 WHOUSE 
I 13 17 COLOR 
I 18 20 WEIGHT 
I 21 24 QTY 
COUT60A D 04 

0 PN 3 

0 PNAME 10 

0 4 "i" 

0 WHOUSE 12 

0 COLOR 17 

0 WEIGHT 20 

0 QTY 24 
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To create an indexed file in unordered sequence, make the same entries as 
for an ordered sequence and specify U in column 66 (Unordered). 


8.8 Adding Records to Files 


After you create a file, it may be necessary to add new records to the file. 
You can add records to a file during detail-time or total-time output, or by 
using exception output. Sections 8.8.1 through 8.8.3 explain how to add 
records to files on the basis of their file organization. 


8.8.1 Adding Records to a Sequential File 


Because the location of each record in a sequential file is fixed in relation 
to all others, there is no unused space where a new record might be 
inserted. Therefore, you can add records to a sequential file only at the 
end of the file, as shown in Figure 8-8. 
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Figure 8-8: Adding Records to the End of a Sequential File 
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To add a record to the end of a sequential file, you must make the 
following entries in its File Description specification: 


e Column 15 (file type)—specify O to indicate the creation of a new 
record. 


¢ Column 19 (record format)—specify F or V to describe the record 
format. 


¢ Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 


¢ Column 66 (file addition)—specify A to cause VAX RPG II to add new 
records to the file. 


You must also make the following entries in the file’s Output specification: 


e Columns 7 through 14 (file name)—define the output file name. 


¢ Columns 16 through 18—specify ADD to identify the record to be 
added. 


The following example accepts input from the terminal and writes records 
to the end of the file LOG. . 
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OQ. ie rh ee Po ee Pe 4 ras te a Ge he eT 





12345678901234567890123456789012545678901234567090123456789012345670901254567090 
TTY 


FINPUT IP F 80 

FLOG 0 6*F 80 DISK A 
TINPUT 01 

I {1 80 DATA 


OLOG DADD 01 . 
0 DATA 80 
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8.8.2 Adding Records to a Direct File 


To add a new record to a direct file, you can either specify the relative 
record number of an empty cell or add the record at the end of the file, as 
shown in Figure 8-9. 


Figure 8-9: Adding Records to a Direct File 


cy jefed fe! 
7 
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To add records to empty cells in a direct file, you must make the following 
entries for the file in its File Description specification: 


¢ Column 15 (file type)—specify I or U to indicate that the file is to be 
opened for input or update. 


e Column 16 (file designation)—specify C or F to indicate a chained or 
full-procedural file. 


e Column 19 (record format)—specify F or V to describe the record 
format. 


e Columns 24 through 27 (record length)—specify the length of fixed- 
length records or the maximum length of variable-length records. 
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° Column 28 (mode)—specify R to access records randomly, using a 
relative record number. 


¢ Column 66 (addition) —specify A to add records to the file. 


You must also make the following entries in the Calculation specification: 


° Columns 18 through 27 (factor 1)—specify the relative record number 
of the empty cell. 


¢ Columns 28 through 32 (operation code)—specify the CHAIN oper- 
ation code. Use an indicator in columns 54 and 55 to check whether 
the cell is empty. The indicator will be set on if the cell is empty. If 
the cell is empty and | an indicator is not specified, a run-time error 
occurs. 


e Columns 33 through 42 (factor 2)—specify the name of the file to 
which you want to add the record. 


Finally, you must make the following entry in the Output specification: 


¢ Columns 7 through 14 (file name)—define the output file name. 
e Columns 16 through 18—specify ADD to identify the record to add. 


The output operation must follow the CHAIN operation, but before the 
next CHAIN operation. If not, the output will be to the cell specified by 
the second CHAIN operation. 


The following example reads a primary input file and adds records to the 
direct file DIRECT. The input field RECNO specifies the record cell to 
which the field is written. 


Ge oe whos Ped SL a ee in ee OL eee ak 





123456 78901234567890123456789012345678901234567890123456789012345678901234567890 
FINPUT. IP F 35 DISK 
FDIRECT IC F JOR DISK A 
FTTY D 6F 30 TTY 
TINPUT 
I 4 30 DATA 
I 31 JS50RECNO 
IDIRECT 
¢ . RECNO CHAINDIRECT 99 
C. N99. "EXISTS’ DSPLYTTY 


ODIRECT DADD 99 
0 DATA 30 
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8.8.3 Adding Records to an Indexed File 


If the file is an indexed file, you can add records at any location. The key 
values for the new records are placed in the index and the entire index is 
sorted in ascending sequence. 


NOTE 


When adding records to an indexed file, you cannot specify A in 
column 66 (file addition) of the File Description specification for 
indexed files processed sequentially within limits or processed 
by an ADDROUT file. 


You can add new records to an indexed file while processing the file 
by specifying an A in column 66 (file addition) of the File Description 
specification. The file can be an input or update file that is processed 
sequentially or randomly. If you want only to add records, you can 
specify an output file. 


You must also make the following entries in the Output specification: 


e Columns 7 through 14 (file name)—define the output file name. 


e Columns 16 through 18—specify ADD to identify the records to be 
added. 


The following program adds records to an indexed file using the ADD 
option on the Output specification: 


On A a eet a 8 ee OP ar i te? Nee ee ol 





1234567890123456789012345678901 23456 7890123456 7890123456 7890123456 7890123456 7890 
FIDXIO1 IP F 24 DISK 
FOUT43A O F 24 «SAI i DISK A 
IIDXIOi AA 


I | 1 24 PN 
OOUT43A DADD NIP 
0 PN 24 
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8.9 Updating Records in Files 


VAX RPG I allows you to update the records in a primary, secondary, 
demand, full- -procedural, or chained file. VAX RPG II allows you to 
update the records in a sequential file only if the records are of fixed 
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length. You can update a record in a primary or secondary file only once 
during the program cycle at detail time. Unlike other types of update files, 
records in a chained, full-procedural, or demand file can be updated at 
detail time or at total time. 


To update a record, you must retrieve the record you want to change, 
change the contents, and then write the record back to the file. You need 
only specify the fields to be changed in a record. The remainder of the 
record is rewritten, using the data that was read into the input buffer. 


You can use a data structure to update a record. See Chapter 12 for an 
example of updating files with data structures. 


VAX RPG II allows you to change the length of a variable-length record 
being updated. VAX RPG II determines the length of the record by 
using the highest end position (columns 40 through 43 of the Output 
specification) of any field in the record. If you need to change the contents 
of a field in the middle of a variable-length record, but do not want to 
change the length of the record, you must define the length of the record 
by defining a one-character field in the last character position of the 
record. 


The following example updates records in the master file MASTER. 
MASTER contains two different record types of different lengths. Both 
records contain the field EMP# that must be updated in different character 
positions. The fields LNGTH1 and LNGTH2 ensure that the records are 
updated using the correct length. The records of type 01 are 80 characters 
long. The records of type 02 are 60 characters long. 


a a a a 





12345678901234567890123456789012345678901234567990123456789012345678901234567890 
FTRANSACTIP F 20 . DISE. a 


FMASTER UC V BORZIAT 1 DISK 

ITRANSACT 

I { 20 NAME 
I 21 25 NEWH 
IMASTER Oi 1 CA 

I 36 40 EMP# 
I 80 80 LNGTHi 
I O2 i CB 

I 46 50 EMPH 
I 60 60 LNGTH2 
C* Update record type 01 

¢ MOVEL’ A’ KEY 24 

C MOVE NAME KEY 

C KEY CHAINMASTER 

C EXCPT 

¢ SETOF 04 
C* Update record type 02 

C MOVEL’B’ KEY 21 

C KEY CHAINMASTER . 

C EXCPT 

OMASTER E 04 . 

0 NEWH 40 

0 LNGTH4 80 

OMASTER E 02 

0 NEWH 50 

0 LNGTH2 60 
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To update the records in a direct or indexed file and simultaneously add 
new records, you must make the following entries for the file in its File 
Description specification: 


e Column 15 (file type)—specify U to indicate that the file is to be 
opened for update. 


e Column 66 (file addition)—specify A to add new records to the file. 


You must also define both Input and Output specifications for the file 
to be updated. Enter ADD in columns 16 through 18 of those Output 
specifications that identify the records to be added. The output records 
without ADD in columns 16 through 18 identify those records to be 
updated. 
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You can update records in an indexed file randomly by key, sequentially, 

or both randomly and sequentially if the file is defined as a full-procedural 

file. To specify an indexed full-procedural file to be processed in the 

update mode, you must make the following entries for the file in its File 

Description specification: 

¢ Column 15 (file type)—specify U to indicate that the file is to be 
opened for update. 


° Column 16 (file designation)—specify F to indicate a full-procedural 
file. | 


e Column 32 (file organization)—specify I to indicate an indexed file. 


8.10 Deleting Records from Files 


You can delete records only from update, direct, and indexed files. To 
prevent the deletion of needed records, perform the following steps: 


e = Retrieve the record. 
e Evaluate its contents. 


e Based on the results of the evaluation, set an indicator to control 
deletion of the record. 


The last record retrieved from the file is the one that is deleted when you 

specify DEL in columns 16 through 18 of the Output specification. You do 
not need to describe any fields in the output record, because the operation 
deletes the entire record. 


The following example deletes a record in the master file MASTER, 
depending on the keys read from the file DELETE: 





) 1 2 | 3 4 | 4) | 6 | ? 
123456789012345678901 23456 7890123456 78901234567890123456789012345678901234567890 

FDELETE IP F 4 DISK 

FMASTER UC F 5OR 4AI 47 DISK A 

FTTY D oF 80 TTY | . 

IDELETE 

I 4 4 KEY 

IMASTER 

C KEY CHAINMASTER 99 

¢ 99 "NOTFOUND’ DSPLYTTY 


OMASTER DDEL N9SNIP 
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8.11 Processing Files with Matching Records 


Matching fields can be used with primary and secondary files to check the 
sequence of records and to define the order in which records are selected 
from multiple files. 


To use matching fields to verify that the records in the file are in sequence 
(either ascending or descending), you define one or more fields to be 
checked by specifying a matching field value (M1 through M9) in columns 
61 and 62 in the Input specification. Then, your program checks the 
sequence by comparing the matching field of one record with the matching 
field of the previous record. If the field is out of order, a run-time error 
occurs. 


8.11.1 Checking Record Sequence for One Record Type 


You designate a record sequence by specifying A or D (ascending or 
descending) in column 18 of the File Description specification. Assign a 
matching field value (M1 through M9) to one or more of the fields you 
want to use as matching fields in columns 61 and 62 (matching field) 

of the Input specification. When you specify more than one matching 
field, assign M9 to the most important field. Your program considers all 
matching fields as one contiguous field with the M9 field in the leftmost 
position, next to the M8 field, and so on, until you reach M1, even though 
the fields may not be adjacent in the record or in numeric (M9 through 
M1) order. 


8.11.2 Checking Record Sequence for More Than One Record Type 


The fields in a record of one type can be in a different order than the 
fields in other record types in the same file. For example, in a payroll file 
consisting of two different record types, one type represents commission 
payment and the other type represents salary. All employee records are 
to be in ascending sequence according to district (DSTRCT). Records 

in a district are to be in ascending sequence according to department 
and employee number. Therefore, three fields (DSTRCT, DEPT, and 
EMPNUM) must be checked in each record. The matching field value M3 
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is assigned to DSTRCT, the most important field; M2 is assigned to DEPT, 
the next most important field; and M1 is assigned to EMPNUM, the least 
important field. Refer to the following example: 


Sequence (AA-ZZ, 01-99) 
| Number (1-N) 


| lOptional/External (OU) Decimal positions 
| |lRecord identifying indicator | Control level 
1 tll | | Match field 
| Ill + Identifying codes + Format | | | Fld ree rel 
File Poult 1 | (PB) IField | J | . 
name 1 ttl ol C C Cl IField Iname | | 1 Field 
| Lull f Z Z Z| location! | | | | indicatrs 
1 oud 1 | 


Pos NDcPos NDcPos NDc IFr To lI 

| 1 | 2 | 3 | 4 | 5 

12345678901234567890123456 7890123456 7890123456 78901234567 
4% H RRR R--- RAH t: *¥ 

IPAYROLL AA O1 80 CC 


“0 








25 27 EMPNUM Mi 


BB 02 80 CS 
4 3 DEPT M2 
8 9 DSTRCT M3 
13. 172SALARY 
25 27 EMPNUM Mi 


Sete et et et et et es 
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First, the program determines the record type. Then, it looks at the 
matching fields for the same record type. 


In the preceding example, the same three matching fields (DSTRCT, 
DEPT, and EMPNUM) appear in both record types and are the same 
length. 
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The length of matching fields assigned to the same match code must be 
the same length for each record type. Table 8-2 shows that this is true for 
the following example: 


IPAYROLL AA O1 80 CC <— first record type 
4 3 DEPT M2 
6 7 DSTRCT M3 
25 27 EMPNUM Mi 
BB 02 80 CS ~€— second record type 
4 3 DEPT M2 
8 9 DSTRCT M3 
25 27 EMPNUM Mi 


tt dt ed ed 
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Table 8-2: Matching Field Lengths 


Record Matching Field Field 
Type Field Location Length 
first DSTRCT 6 to 7 2 
DEPT 1 to3 3 
EMPNUM 25 to 27 3 
8 <— total 
second DSTRCT 8 to 9 2 
DEPT 1 to 3 3 
EMPNUM 25 to 27 3 
8 <— total 


Matching fields need not be specified for all the record types in a file. 
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8.11.3 Using Matching Fields with Field-Record-Relation Indicators 


Although there may be different record types in a file, the fields for each 
record type are often the same. Many fields have the same name, contain 
the same data, and are in the same character positions for all the record 
types in a file. When only a few fields differ, you can describe more than 
one record type in an OR relationship. Refer to the following example: 


Sequence (AA-ZZ, 01-99) 
1 Number: (4-N) 









| lOptional/External (OU) Decimal positions 
| IlRecord identifying indicator Control level 
PU I | Match field 
Pull + Identifying codes + Format I. | | Fld reo rel 
File i 1 | (PB) IField | ft J 
name 1 ttl C ¢ C! IField Iname 11 | Field | 
| Pett Z Z . ZI tlocation!| | | | indicatrs 
Il. | l1).Pos NDcPos NDcPos NDc IFr To Il- ais AE Bankes 
| 2 | 3 | 4 I 5 | 6 | 7 | 
1234567890123456 7890123456 789012345678901234567890123456789012345678901234567890 
4% HORRR Bem Rem RR 
IPAYROLL AA O01 80 CS 
I OR 02 80 CM 
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You specify common fields only once, because they apply to both record 
types. The field-record-relation indicators specified i in columns 63 and 64 
of the Input specification identify the fields unique to a particular record 
type. Therefore, the COMM field in the following example is associated 


with record type 01 and the SALARY field is associated with record type 
02. 


The DSTRCT, DEPT, and EMPNUM matching fields are ne in checking 
the sequence of the records in the PAYROLL file, and the matching-field 
values M1, M2, and M3 are described only once in columns 61 and 

62 without any field-record-relation indicators in columns 63 and 64. 
Therefore, the matching fields and their values apply to both record types 
(01 and 02) as shown in the following example. 
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Sequence (AA-ZZ, 01-99) 

| Number (1-N) 

1 [Optional/External (QU) Decimal positions. 

| (tRecord identifying indicator | Control level 
| | Match field 
| 

| 

| 

. 


111 
uae 111 + Identifying codes + Format | — 1 | Fld rec rel 
File Hr | | (PB) Field | 1 1 
name Ht C ¢ Cl lField tname | I | Field) 
| Hit Z Z ~~—sZI:sN location! | 1 1 | indicatrs 
Td 111 Pos NDcPos NDcPos NDco ifr fo Ji  tidi-t+- 9 | ™ 
fH) | 6 
901234567 
x% ee ee eT HER HHH waa 
IPAYROLL AA O41 80 CS 
I OR 02 80 CM 
I 1 3 DEPT M2 
I 8 9 DSTRCT M3 
I 25 27 EMPNUM Mi 
I 44 152COMM O41 
I 43 172SALARY 02 
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If one of the matching fields is in a different record position for each 
record type, you must assign matching field entries, as shown in the 
following example: 


Sequence (AA-ZZ, 01- -99) 
| Number (1-N) 


| lOptional/External (OU) Decimal positions 
| |tRecord identifying indicator | Control level 
til | | Match field | 
|) (lt + Identifying codes + Format = | | | Fld rec rel 
File Pill ol 1 | (PB) IField | 1d. 
name 1 ult | ¢ ¢C Cl IField = Iname | | | Field 
| | a | Z fd Z| Ilocation! | | | 
1 til | | 


| indicatrs 
| 





1 Pos NDcPos NDcPos NDc IFr To Il + - 0. 
j 2 | 3 | 4 | ) 
901234567 
xe HORER Bem Bem em RRR 8 KRREER, 
IPAYROLL AA 04 80 CS 
I OR 02 80 CM : 
I 1 3 EMPNUM Mi 
I 20 24 DSTRCT M3 
I 6 72COMM O1 
I 40 12 DEPT M204 
I § 7 DEPT M202 
I 10 142SALARY 02 
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For a 01 record type, matching field DEPT is in field location 10 through 
12. For a 02 record type, matching field DEPT is in field location 5 
through 7. 


8.11.4 Using Matching Fields to Process More Than One File 
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The processing of a primary file with one or more secondary files is called 
multifile processing. In multifile processing without matching fields, 

VAX RPG II first reads all the records from the primary file, then reads 
all the records from each secondary file in the same order in which they 
are specified in the File Description specification. By using matching 
fields, your program can select the records from the secondary file before 
selecting the records from the primary file, based on the value of their 
matching fields. 


When you use matching fields to process more than one file, the program 
selects records according to the contents of the matching fields, as follows: 


e One record is read from every file and the matching fields are com- 
pared. If the records are in ascending sequence, the record with the 
lowest matching field value is selected for processing. If the records 
are in descending sequence, the record with the highest matching field 
value is selected for processing. 


e¢ When a record is selected from a file that is then processed, the next 
record from the file is read. The new record is then compared with 
the other records not selected in the previous cycle. 


You can combine records with and without matching fields in the same 
file. Records without matching fields are processed before records with 
matching fields. If two or more of the records being compared have no 
matching fields, selection of those records is determined by the priority of 
their files, as follows: 


e The records in primary files are processed before the records in 
secondary files. 


e The records in secondary files are processed in order of appearance in 
the File Description specifications. 


Table 8-3 shows that the matching fields from a primary file are com- 
pared with the matching fields from a secondary file to select records in 
ascending sequence. The letters represent the data in the matching fields. 


Table 8-3: Matching Primary and Secondary File Field 


Values 
Record Number Primary File Secondary File 
1 | A B 
2 Cc D2 
3 D1 X 
4 F Z 


Figure 8-10 shows the logic flow when your program uses matching fields 
to do multifile processing. A keyed list follows the figure. 
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Figure 8-10: Using Matching Fields For Multifile Processing 


Primary File Secondary File 


i Record 1 2. B Record 1 







Process A. 


fields. 






Process B. 





fields. 





Cycle n+ 1 







Record 1 






Process C. 





Cycle n + 2 





(Continued on next page) 
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Figure 8-10 (Cont.): Using Matching Fields For Multifile Processing 


e D1 | Record 3 





fields. 






Cycle n+ 3 


Compare 
match 
fields. 












Cycle n+ 4 


Compare 
match 
fields. 










Process F. 


Cycle n+ 5 





mE 
* 
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Key to Figure 8-10: 


The first record of the primary file is read and the matching field (A) 
is located. 


The first record of the secondary file is read and the matching field (B) 
is located. 


The contents of the matching field (A) of the first record in the primary 
file are compared with the contents of the matching field (B) of the 
first record in the secondary file. A is selected. 


The second record of the primary file is read and the matching field 
(C) is located. 


© The contents of the matching field (B) of the first record in the sec- 


ondary file are compared with the contents of the matching field (C) 
of the second record in the primary file. B is selected. 


The second record of the secondary file is read and the matching field 
(D2) is located. . 


The contents of the matching field (D2) of the second record in the 
secondary file are compared with the contents of the matching field 
(C) of the second record in the primary file. C is selected. 


The third record of the primary file is read and the matching field (D1) 
is located. 


The contents of the matching field (D2) of the second record in the 
secondary file are compared with the contents of the matching field 
(D1) of the third record in the primary file. D1 is selected. 


@ The fourth record of the primary file is read and the matching field (F) 


is located. 


The contents of the matching field (D2) of the second record in the 
secondary file are compared with the contents of the matching field 
(F) of the fourth record in the primary file. D2 is selected. 


@ The third record of the secondary file is read and the matching field 


(X) is located. 


The contents of the matching field (F) of the fourth record in the 
primary file are compared with the contents of the matching field (X) 
of the third record in the secondary file. F is selected. Because the 
primary file is now at its end, the remaining records in the secondary 
file (X and Z) are processed in order of appearance. 


When the matching fields in a primary file match one or more of the 
matching fields in the secondary files, VAX RPG II sets the matching- 
record (MR) indicator on before detail-time calculations. You can use the 
MR indicator to condition calculation and output operations for the record 
just selected. The indicator remains on for one complete program cycle. 
It is set off if the record selected for processing contains no matching 

_ fields. A record selected using the FORCE operation code causes the MR 
indicator to remain off for one program cycle while the forced record is 
processed. 


VAX RPG II processes matching records for two or more files in the 
following ways: 


e When a record from the primary file matches a record from the 
secondary file, the record from the primary file is processed before the 
record from the secondary file is processed. The record-identifying 
indicator that identifies the record type just selected is on at the time 
the record is processed. 


e When records from ascending files do not match, your program 
processes the record with the lowest matching field content first. 


¢ When records from descending files do not match, your program 
processes the record with the highest matching field content first. 


e A record type that has no matching field specification is processed 
immediately after the previous record is processed. In this case, the 
MR indicator is set off. If this record type is the first in the file, your 
program processes this record first, even when it is not in the primary 
file. 


¢ The matching of records makes it possible to enter data from primary 
records into their secondary records because your program processes 
the record from the primary file before matching the record from the 
secondary file. However, the transfer of data from the secondary 
record to matching primary records can be done only when look- 
ahead fields are specified. 


In the following example, matching fields are used to combine a primary 
file with two secondary files in ascending sequence. Record-identifying 
indicators are assigned in the following way: 

¢ 01—Records from the primary file with matching fields 

e¢ 02—Records from the primary file without matching fields 

¢ 03—Records from the first secondary file with matching fields 
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¢ 04—Records from the first secondary file without matching fields 
e 05—Records from the second secondary file with matching fields 
¢ 06—Records from the second secondary file without matching fields 


0) | i | 


Q 


| 2) | 6 | 7 | 





eA. | | Ca 


FRECI99A IP AF 
FRECIS9B IS F 
FRECI99C IS F 


FOUTPUT O F 
IRECI99A (OL 
; , 

I 

I 02 
: 3 
IRECI99B «3 
i : 

I 

I 04 
I 

IRECI99C =O 
I 

I 

I 06 


I 
QOUTPUT D 
0 


80 
80 
80 
80 Ci 
80 C2 


80 C3 


80 C4 
80 C5 


80 C6 
NiP 


B0 TEXT 
2 MATCH Mi 


80 TEXT 


80 TEXT 
2 MATCH M4 


80 TEXT 


80 TEXT 
2 MATCH Mi 


80 TEXT 
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Table 8-4 lists the contents of the matching fields for all three files: 
primary, first secondary, and second secondary. Field values with A after 
the value represent values from the primary file. Field values with B after 
the value represent values from the first secondary file. Field values with 
C after the value represent values from the second secondary file. 
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Table 8-4: Matching Field Values 


Record 
Number 


1 


oo ON BDA Oo FP WD NY 


Primary 
File 


none 
none 
20A 
20A 
40A 
50A 
none 
60A 
80A 


First Secondary 
File 


none 
20B 
30B 
30B 
60B 
none 
70B 
80B 
80B 


Second Secondary 


File 
10C 
30C 
50C 
50C 
none 
60C 
80C 
80C 


none 


Table 8-5 lists the steps involved in processing the files in Table 8-4 and 
those indicators that must be set on for the operation to occur. 


Table 8-5: Processing Records with Matching Fields 
Matching Field Value 


Step 


co ON HD OF FP WD N = 


- SS SS eS ee 
= WO NO F © 


Record Type 


02 
02 
04 
05 
01 
01 
03 
03 
03 
05 
01 
01 
02 
05 


none 
none 
none 
10C 
20A 
20A 
20B 
30B 
30B 
30C 
40A 
50A 
none 
50C 


Indicators for Processing — 


Not MR and 02 
Not MR and 02 
Not MR and 04 
Not MR and 05 
MR and 01 
MR and 01 
MR and 03 
Not MR and 03 
Not MR and 03 
Not MR and 05 
Not MR and 01 
MR and 01 
Not MR and 02 
MR and 05 
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Table 8—5 (Cont.): Processing Records with Matching Fields 
Step Record Type Matching Field Value - Indicators for Processing 


15 05 50C MR and 05 
16 06 none Not MR and 06 
17 01 60A MR and 01 
18 03 60B MR and 03 
19 04 none Not MR and 04 
20 05 60C MR and 05 
21 03 70B Not MR and 03 
22 01 80A MR and 01 
23 03 80B MR and 03 
24 03 * 80B . MR and 03 
25 05 80C MR and 05 
26 05 80C MR and 05 
af 06 none Not MR and 06 


8.12 Processing Files with Multiple Keys 


The following program reads one input file with three keys. It uses three 
different file specifications to gather the three keys. Note that the three 
file names use identical fields, and that each file name uses a different key 
to point to the same file. Also note the use of the same fields by a data 
structure. 
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"0 


FIDXI04 
FIDXJO4 
FIDXK04 
FIDXO3A 
TIDXIO4 


IDXJO4 


IDXK04 
FIELDS 


IDXO3A 


| ce ee oe oe ee oe ee ee ee | 


1 


BB 


cc 


DS 
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NiP 


4Al 2 

SAI 

e2Al | 
FIELDS 


| 
123456 7890123456 7890123456 7890123456 7890123456 7890123456 789012345678901234567890 


4 DISK 
4 DISK 
4 DISK 

DISK. 


24 


| 6 | 7 | 





IDXI04 
IDXIO4 


{ 3 PN 

4 10 PNAME 
41 12 WHOUSE 
13 17 COLOR 
18 20 WEIGHT 
21 24 QTY 


4 3 PN 

4 10 PNAME 
44 412 WHOUSE 
i317 COLOR 
48 20 WEIGHT 
21 24 QTY 


4 24 FIELDS 


1 3°PN 
4 10 PNAME 
14 12 WHOUSE 
13 17 COLOR 
18 20 WEIGHT 

21 24 QTY 
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The VAX RPG II compiler creates one buffer for each file in a 
VAX RPG II program. However, there are some programs in which input 
and output buffers for the same file should be distinct. 
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As an example, consider a program that is sequentially reading an indexed 
file and occasionally executing the ADD operation code in the file using 
EXCPT processing at total time. At the beginning of the logic cycle, a 
record is selected for input. (For this example, use the FOO record.) When 
a control break occurs, the program does some total-time processing and 
ends with an EXCPT operation on the same file. This results in a new 
record being added to the file, for example the BAR record. Continuing 
with the normal logic cycle, the program enters detail time and the record 
selected for input has become the BAR record which was just written 
instead of the expected FOO record. The same buffer is used for both | 
input and output. When the BAR record is written, the record buffer is 
overwritten and its previous contents lost, so that when it is time for field 
extraction to occur, the wrong record is found. 


There are a number of workarounds that you can use. The ADD records 
could be written to a distinct output file and merged with the master files 
outside of the application. Or, you can use the total-time processing to 
save the record to be written, and set an indicator on. Then, during detail- 
time processing, use the indicator to trigger the EXCPT operation. Because 
the fields of the input record have been populated by this time, no conflict 
occurs with a single record buffer. 


The best alternative is to open two streams to the same file and have two 
F specifications which effectively refer to the same file. Normal input 
processing takes place using one stream and all ADD processing occurs 
on the other stream. Because a record buffer is allocated for each file, two 
buffers are created in this scheme, and no conflict occurs. Both files need 
to use the file sharing option (S in column 68 of the F specifications) in 
this case. 


Only one update is allowed for each logic cycle for update files other than 
demand and chained files. 
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Using Printer Output Files 


If you want to create a formatted report by printing an output file, you 
must decide what the report will look like before you write your program. 
You must know what information is to be printed on each heading, detail, 
and total line, and where the individual fields are to appear. 


Designing the physical layout of your report is an important part of the 
work necessary to produce a formatted report. VAX RPG II provides 
several features you can use to print certain information automatically and 
to control the printing of other information. Sections 9.1 and 9.2 describe 
these features and explain how to use them. 


NOTE 


Printer output files cause a file to be in VAX/VMS print-file 
format. The default PRINT command causes the insertion 

of a form-feed character when the form nears the end of a 
page. To suppress the insertion of form-feed characters, use 
the /NOFEED qualifier on the PRINT command when printing 
printer output files created by VAX RPG II programs. 


| 
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9.1 Editing Output 


VAX RPG II has several means of structuring and editing your program 
output: 


e Edit codes are one-letter codes you can specify in column 38 of your 
Output specification to edit the data in a numeric output field. 


¢ Constants are single-quoted literals (for example, ‘foobar’) you can 
specify in columns 45 through 70 of the Output specification to 
describe or label printer output columns, rows, and other items of 
importance to the program output. 


e Edit words are special instructions placed in columns 45 through 70 
of the Output specification that affect the sign of numeric data, the 
body of the field to be edited, and the characters that will be printed 
regardless of the sign. Certain digit selection, zero suppression, blank 
insertion, and currency symbol manipulation are all controlled by edit 
words. 


You can use predefined edit codes and edit words to format numeric 
data for your report. Edit codes and words supply additional information 
about the output, thus increasing your report’s usefulness to the end 
user. Section 9.1.2 describes constants and explains how to use them. 
Section 9.1.1 describes edit codes and their modifiers and explains how to 
use them. See Chapter 15 for detailed information on edit words. 


9.1.1 Using Edit Codes and Edit Code Modifiers 


You can specify specialized editing for numeric data by entering one of 
the one-character edit codes in column 38 of the Output specification. 
Edit codes consist of (1) simple edit codes (X, Y, and Z) that perform one 
predefined function, and (2) combined edit codes (1, 2, 3, 4, A, B, C, D, 
J, K, L, and M) that perform a combination of predefined functions. See 
Chapter 15 for detailed information on edit codes. 


In most cases, using one or more edit codes to format numeric data 

is sufficient. However, in some cases you might want to use an edit 
code modifier for special formatting such as replacing leading zeros with 
asterisks (*) or putting a dollar sign ($) immediately to the left of the 
leftmost character. 


See Chapter 15 for detailed information on edit code modifiers. 
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9.1.2 Using Constants 


Constants are used to specify headings that describe the contents of 

a particular column. To specify a constant, enter the constant string, 
enclosed in apostrophes, in columns 45 through 70 (constant or edit 
word). In the following example, SALES REPORT appears in character 
positions 24 through 35 of the printed output file: 






Type (HDTE) Edit codes , ONOCR - 
IFetch ofl / Rel (FR) | X jj = seeeereccen== 
1 |Space | Y date edit YYiAad 
111 Skip | Z zero suppress Y N 2 B K 
Hit | NY 3 CL 
1ft lt Indicators IBlank-after (B) N N 4 D M 
File tl ft | Field I!End position 
name Ht | name JIl Format (PB) 
| tt | | HI | 
Ol 1 1BAB A NxxNxxNx«x | Hl I+ Constant or edit word + 
) eer | | 2 | 3 | 4 | 5 i 6 | 
123456789012345678901234567890123456 7890123456 7890123456 7890123456 78901234567890 
¥% RREKK HX ¥ HHK--— HE weine 
0 35 ‘’SALES REPORT’ 
ZK-4415-85 
Rules 


e Constants can contain from 1 to 24 characters. 


e Enclose constants in apostrophes (for example, ‘EMPLOYEE NAME’). 
The apostrophes are not printed. 


¢ When using constants, leave columns 32 through 39 and column 44 
blank. | 
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9.2 Using Special Words 


VAX RPG II provides special words that enable you to perform the 
following kinds of formatting: 
e Printing the date on every page 


e Printing a page number and incrementing the page number by one for 
each new page . 


¢ Repeating data fields in an output record 


This section describes special words and explains how to use them. 


9.2.1 Printing the Date: UDATE, UDAY, UMONTH, UYEAR 


UDATE automatically prints the date in the format mm-dd-yyyy. To put 
slashes ( /) between the fields (for example, 05/27/1986), specify Y in 
column 38 of the Output specification. 


The default date is the system date. To change the default date, define the 
logical name RPG$UDATE to the date format you want. The following 
example changes the date to June 12, 1986, using the format 
dd-mmm-yyyy: — 


$ DEFINE RPG$UDATE "12-JUN-1986" 


You can change the UDATE output format by specifying D, L, or J in 
column 21 of the Control specification. Specifying D changes the UDATE 
format to dd-mm-yyyy. Specifying I or J changes the UDATE format to 
dd.mm.yyyy. 
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You can use UDAY, UMONTH, and UYEAR to print each component of 
the date in the format you need, as shown in the following example: 





Type (HDTE) Edit codes , ONOCR - 
Fetch ofl / Rel (FR) |X seeee= soon--- 
1 1Space | Y date edit YYiLaAadJ 
IT! Skip | Z zero suppress Y N 2 B K 
ttl | | NY 3 CL 
111 1 Indicators IBlank-after (B) N N 4 D M 
File Hl Field IlEnd position 
name Wt | name II1 Format (PB) 
| litt | | 11 | 
0! 1 1BAB A NxxNxxNxx | 1 I+ Constant or edit word + 
| 2 | 3 | 4 l 5 l 6 ? | 
TEAS SRA ED ASI a PA ee Re EE 
ry HHKRH H % a a ; 
0 H iP 
0 UYEAR 8 
0 _ 9 , eae 
0 UMONTH ii 
0 3 42 fee 
0 UDAY 14 
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In this example, the special words UYEAR, UMONTH, and UDAY in the 
Output specification change the date format to yy-mm-dd. The output 
might look like this: 


83-05-16 
Rules 


e You cannot specify Y in column 38 (edit code) of the Output specifi- 
cation for UDAY, UMONTH, or UYEAR. Instead, specify a constant 
in columns 45 through 70 (constant or edit word) to separate the day, 
month, and year. 


e You can use these special words in factor 1 or 2 of the Calculation 
specification. 


e You cannot use these special words in the result field of the 
Calculation specification. 


e You cannot use the blank after option (column 39 of the Output 
specification) with these special words. 
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9.2.2 Printing the Time 


The TIME operation code on a Calculation specification prints the system 
time of day on your program output. 


See Section 16.11 for more information on using the TIME operation code. 


9.2.3 Numbering Pages: PAGE and PAGE1 through PAGE7 


VAX RPG II provides eight special words, PAGE and PAGE1 through 
PAGE7, for numbering pages in printed output files. VAX RPG II auto- 
matically increments the page number by one for each new page. You can 
use more than one special word to page number several different output 
files. For example, if your program produces four different reports, each 
of the four can have its own page numbering sequence by using PAGE1, 
PAGE2, PAGE3, and PAGE4. A total of eight concurrent page sequences 
is possible (using PAGE through PAGE7). 


To use one of the special words for page numering, specify it as a field in 
the Input, Calculation, or Output specification. When you use a special 
word for page numbering as an input field or as the result field of a 
calculation, you can use any field length up to 15 digits, but you must 
specify zero decimal positions. VAX RPG II suppresses leading zeros and 
signs on output unless you use an edit word or an edit code, or specify a 
packed decimal or binary data format. 


If you do not define the length of a special word for page numbering 
elsewhere (for example, defining a field to represent the page number as a 
result of a calculation), the page number is output as a four-digit numeric 
field with zero decimal positions. Page numbering begins with 1. 


9-6 Using Printer Output Files 


To change the beginning page number, enter the page number you want 
to use as an input record and name the field PAGE or use a PAGE field as 
the result of a calculation. Enter the field in columns 53 through 58 of the 
Input specification, as shown in the following example: | 





0) | 1 | a 3 4 | 4) | ) | 7 | 
123456 7890125456 7890125456 7890125456 7890123456 7890123456 789012345678901254567890 





IINPUT AA 99 
I 1 40PAGE 


OOUTPUT H 2 4P 


0 OR OF 

0 UDATE Y 8 

0 36 DEPOSIT’ 
0 49’ REPORT! 
0 | 68 'PAGE’ 

0 PAGE 72 
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In the preceding example, the contents of the field PAGE appear in 
character positions 69 through 72. If the value of the field is 0032, the 
page numbering begins with 33, because VAX RPG II adds 1 to the 
number. The output appears as follows: 


0 | 1 | 2 | 3 1 4 | 5 | 6 | T | 
12345678901234567890123456789012345678901 2345678901 2345678901 2345678901234567890 
5/16/83 DEPOSIT REPORT PAGE 33 
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Another way to change the page number is to assign the page number 
you want minus one to a PAGE field in the result field, as shown in the 
following example: 





1234567890123456 7890123456 7890123456 78901234567890123456789012345678901 25456789( 


C N99 Z-ADD89 PAGE 
C SETON 99 


QOUTPUT H 2 iP 
OR 


0 OF 

0 UDATE Y 8 

0 36 DEPOSIT’ 

0 49" REPORT’ 

0 68 ’PAGE’ 

0 PAGE 72 

ZK-44 18-85 
The output appears as follows: 
0 | 1 | 2 | 3°] 4 | § | 6 | 7 | 

123456789012345678901 2345678901 2345678901234567890123466789012345678901234567890 
5/16/83 DEPOSIT REPORT PAGE 90 


In the preceding example, Z-ADD assigns 89 to PAGE. VAX RPG II adds 
1 to this number and begins numbering pages with 90. The assignment 
occurs when indicator 99 is set off so that VAX RPG II makes the initial 
page number assignment only once and not every time a record is read. 


You can restart page numbering at any point in the program. Use any one 
of these methods to reset the value of a PAGE field: 


© Specify the blank after option (column 39 of the Output specification) 
for a PAGE field to reset the page number to 1 after the current record 
is output. 


e Use a PAGE field as the result of an operation in the Calculation 
specification or as an Input field. 


e Use output indicators in the Output specification to condition the 
value of a PAGE field. When the indicator is set on, the value of 
the PAGE field is reset to 1 before the current record is output. You 
cannot use these indicators to control the printing of a PAGE field, 
because a PAGE field is always printed. 
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9.2.4 Saving Time by Repeating Data: «PLACE 


You can use the special word *PLACE to repeat data in an output record. 
The fields or constants you want to repeat must have been previously 
defined. Then, you can use the same fields or constants without hav- 
ing to specify their field names (columns 32 through 37 of the Output 
specification) and end positions (columns 40 through 43 of the Output 
specification). When you specify *PLACE in columns 32 through 37, 
VAX RPG II repeats all the data between the beginning position and the 
highest end position for any previously defined field in the output record. 
To prevent overlapping, the end position on the same Output specification 
as *PLACE must be at least twice as high as the highest end position of 
the group of fields you want to repeat. 


When using *PLACE, the following columns in the Output specification 
that contain *PLACE must be left blank: 


e Column 38 (edit code) 

e Column 39 (blank after) 

¢ Column 44 (data format) 

® Columns 45 through 70 (constant or edit word) 


In the following example, *PLACE specifies these fields again: 


e =6LLIST# 

e DESCR 

¢ STOCK# 

e ONHAND 
e =6PRICE 
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ee ae Be eB I ry 





12345678901234567890123456789012345678901234567890123456789012345678901234567890 
FOUTIS4 IP F : . . . 


FOUT9iA OF F 80 PRINTER 
1* 
IOUTI94 AA Of 
I 1 6 STOCKH 
I 7 18 DESCR 
I 19 2400NHAND 
I 22 262PRICE 
C# 
Cc «(Of LIST# ADD 1 LIST# 30 
O* | 
QOUT9iA D NiP 
0 LIST# Z 4 
0 DESCR 18 
0 STOCKH 26 
0 ONHANDZ 314 
0 PRICE K 39 ’$’ 
0 ¥PLACE 79 
ZK-4419-85 
Sample output from this example might look like the following: 
PARSNIPS VEGiPQ 17 $.89 PARSNIPS VEGIPQ. 17 $.89 


SKIM MILK DAROSK 134 $1.70 
POTATO CHIPS SNK945 100 $1.19 
2 QRT PEPSI DRNKiA 87 $1.29 
BAKED BEANS CANFOD 90 $%.65 


SKIM MILK DAROSK 134 $1.70 
POTATO CHIPS SNK945 100 $1.19 
2 QRT PEPSI DRNKiA 87 $1.29 
BAKED BEANS CANFOD 90 §$.65 


Of © be 
Or WD 


9.3 Conditioning Output Lines 


Although you can use any type of indicator to condition output, the 
first-page (1P) and overflow indicators specifically condition output. 
Sections 9.3.1 and 9.3.2 describe how these indicators condition output. 
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9.3.1 Printing Lines Before Reading the First Record: First-Page Indicator 


You can use the 1P indicator to condition those heading lines you want 
printed before VAX RPG II processes the first record. 


You specify the 1P indicator in columns 24 and 25, 27 and 28, or 30 and 
31 of the Output specification. 


See Section 7.2.1 for complete information on the 1P indicator, including 
a program example to print heading lines before reading the first record. 


9.3.2 Specifying Page Breaks: Overflow Indicator 


You use overflow indicators to specify when a page break should occur 
before certain lines are printed. These indicators are used primarily to 
condition the printing of heading lines, but can also be used to condition 
calculation operations and other types of output lines. 


You can use overflow indicators only for output files going to the printer. 
You define the indicator in columns 33 and 34 of the File Description 
specification. The same overflow indicator must be used to condition 
the overflow lines for that same file. If no indicator is specified for that 
file, VAX RPG II automatically handles overflow. See Section 9.4 for 
information on automatic overflow. 


VAX RPG II sets on an overflow indicator only the first time an overflow 
condition occurs for the current page. An overflow condition exists 
whenever one of the following occurs: 

e A line is printed on the overflow line. 

e A line is printed past the overflow line. 

e The overflow line is passed during a space operation. 

e - The overflow line is passed during a skip operation. 


e Spacing past the overflow line sets the overflow indicator on. 


e Skipping past the overflow line to any line on the same page sets the 
overflow indicator on. 


e Skipping past the overflow line to any line on the new page does 
not set the overflow indicator on unless the skip is specified past the 
overflow line on the new page. 
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e A skip to a new page specified on a line not conditioned by an 
overflow indicator sets the overflow indicator off before the form 
advances to a new page. 


° If you specify a skip to a new line and the printer is currently on that 
line, a skip does not occur. 


¢ When an OR line is specified for an output print record, the space 
and skip entries of the preceding line are used. If space and skip 
requirements differ from the preceding line, enter space and skip 
entries on the OR line. 


e An overflow indicator can appear on either line of an AND or an OR 
relationship. In an AND relationship, the overflow indicator must 
appear on the main specification line for that line to be considered 
an overflow line. In an OR relationship, the overflow indicator can 
be specified on either the main specification line or the OR line. 
However, only one overflow indicator can be associated with one 
group of output indicators. 


e If an overflow indicator is used on an AND line, the line is not an 
overflow line. In this case, the overflow indicator is treated like any 
other output indicator. 


e An overflow indicator cannot condition an exception line (E in column 
15 of the Output specification), but can condition fields within the 
exception record. 


During a normal program cycle, VAX RPG II checks whether the over- 
flow indicator is set on only once (immediately after total-time output). 
Detection of the overflow indicator causes the following operations: 


e VAX RPG II prints all total lines conditioned by an overflow indicator 
when the indicator is set on. 


e VAX RPG II prints those heading and detail lines conditioned by an 
overflow indicator when the indicator is set on. 


e Advancement to a new page does not happen automatically. 
Normally, one of the overflow lines specifies a skip to the top of a 
new page. 


If the overflow indicator is set on, you can fetch the overflow routine 


before printing any total or detail line by specifying F (fetch overflow) in 
column 16 of the Output specification. Fetch overflow alters the 
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VAX RPG II logic cycle to prevent printing detail, total, and exception lines 
on or over the perforation between pages. When you fetch the overflow 
routine, VAX RPG Il performs the following operations: 


e When an output line specifies fetch overflow, VAX RPG II checks 
whether the overflow indicator for that file is set on. If it is, VAX 
RPG II calls the overflow routine and prints only those overflow lines 
associated with the file described on the Output specification. 


e After VAX RPG II prints the overflow lines, it prints the line that 
specified the fetch overflow. 


® VAX RPG II prints any detail-time and total-time lines left for that 
program cycle. 


e If you want to fetch the overflow line for each record in an OR 
relationship, you must specify F (fetch overflow) in column 16 for 
each line. 


e You cannot specify an overflow indicator in columns 23 through 31 on | 
the same line with F (fetch overflow) in column 16. 


To decide when to fetch the overflow routine, study all possible overflow 
situations and count lines, spaces, and skips to determine what happens 
when an overflow occurs. 


In the following example, the length of a page is 15 lines. The overflow 
line is line 12. When the overflow line is reached, the overflow indicator 
is set on, which conditions the heading line that prints the date, report 
title, and page number at the top of each page. 
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0) I i | 2 | 3 | 4 a: | 3) I 7 | 





123456 7890123456 7890123456 7890123456 7890123456 7890123456 7890123456 78901234567890 
FOUTI93 IP F 4 
FOUT9ZA O F 80 0G LPRINTER 
LOUT93A 9 4i5FL 120L 

IOUTI93 AA O01 





I 4 5 ZIP 

I 10 150CEN30 
I 46 210CEN40 
I 22 270CEN50 
I 28 330CEN60 
I 34 390CEN70 
I 40 450CEN80 
I 46 47 STATE 
I 48 59 COUNTY 
I 63 74 TOWN 
QOUT9ZA H 102 1P 

0 OR 0G 

0 UDATE Y 10 

0 47 'SOUTHERN NEW HAMPSHIRE’ 
0 53 7 TOWNS’ 

0 PAGE 77 

0 Di 01 

0 TOWN 13 

0 COUNTY 26 

0 STATE 30 

0 CEN80 J 38 

0 CEN70 J 46 

0 CEN60 J 54 

0 CEN4O J 62 

0 CEN40 J 70 

0 CEN3O J 78 
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A sample of the output from this example might look like the following: 


_0 | | | 2 | 3 | 4 | 5 | 6 | 7 | 
12345678901234567890123456789012345678901234567890123456789012345678901 234567890 
12/14/83 SOUTHERN NEW HAMPSHIRE TOWNS 1 


Hampstead Rockingham NH 3,785 2,401 1,261 823 823 775 
Kingston Rockingham NH 4,111 2,882 1,672 1,002 1,002 1,017 
Litchfield Hillsborough NH 4,150 1,420 721 341 341 286 
Newmarket Rockingham NH 4,290 3,361 3,153 2,640 2,640 2,511 
Atkinson Rockingham NH 4,397 2,291 1,017 434 434 407 


Rye Rockingham NH 4,508 4,083 3,244 1,246 1,246 1,081 
Hollis Hillsborough NH 4,679 2,616 1,720 996 996 879 
Peterborough Hillsborough NH 4,895 3,807 2,963 2,470 2,470 2,521 
Raymond Rockingham NH 5,453 3,003 1,867 1,340 1,340 1,165 
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12/14/83 SOUTHERN NEW HAMPSHIRE TOWNS © 2 
5,609 4,712 2,915 1,414 1,414 1,366 


Plaistow Rockingham NH 
Windham Rockingham NH 5,664 3,008 1,317 630 630 538 
Seabrook Rockingham NH 5,917 3,053 2,209 1,782 1,782 1,666 
Pelham Hillsborough NH 8,090 5,408 2,605 979 979 814 
Amherst Hillsborough NH 8,243 4,605 2,051 1,174 14,174 1,115 
Milford Hillsborough NH 8,685 6,622 4,863 3,927 3,927 4,068 
Bedford Hillsborough NH 9,481 5,859 3,636 1,561 1,561 1,326 
Hampton Rockingham NH 10,493 8,011 5,379 2,137 2,137 1,507 
Exeter Rockingham NH 11,024 8,892 7,243 5,398 5,398 4,872 
12/14/83 SOUTHERN NEW HAMPSHIRE TOWNS 3 


Goffstown Hillsborough NH 11,315 9,284 7,230 4,247 4,247 3,839 
Londonderry Rockingham NH 13,698 6,346 2,457 1,429 1,429 1,373 
* Hudson Hillsborough NH 14,022 10,638 5,876 3,409 3,409 2,702 
Merrimack Hillsborough NH 15,406 8,595 2,989 1,253 1,253 1,084 
Derry Rockingham NH 18,875 11,712 6,987 5,400 5,400 6,131 
Salen Rockingham NH 24,124 20,142 9,210 3,267 3,267 2,751 
Portsmouth Rockingham NH 26,254 25,717 26,900 14,821 14,821 14,495 
Nashua Hillsborough NH 67,865 55,820 39,096 32,927 32,927 31,463 
Manchester Hillsborough NH 90,936 87,754 88,282 77,685 77,685 76,834 


9.4 Automatic Overflow 


When an overflow indicator is not assigned to an output file going to the 
printer, the compiler assigns the first unused indicator to the file. This 
causes a skip to line 1 whenever an overflow occurs, and the overflow 
routine executes for this file. 


You can override the printing of overflow lines by specifying an overflow 
indicator on the File Description specification. However, do not use the 
same indicator to condition any output line. This causes continuous 
printing of lines, regardless of page boundaries. 





9.5 Defining the Page Size 


The Line Counter specification allows you to alter the default format of a 
printed output file’. You can use this specification to change the number 
of lines on a page and to change the overflow line. 


1 The default format is 66 lines, with the overflow line at 60. 
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To define the page size, you must make the following entries in the Line 
Counter specification: 


¢ Columns 7 through 14 (file name)—specify the name of the out- 
put file. This file must have been previously defined on the File 
Description specification with PRINTER in columns 40 through 46 
(device code) and L in column 39 (extension). 


¢ Columns 15 through 17 (form length)—specify the number of lines 
printed on a page. 


¢ Columns 18 and 19 (FL)—if you specify an entry in columns 15 
through 17 (form length), you must enter FL in columns 18 and 19. 
This entry indicates to the compiler that columns 15 through 17 define 
the form length. 


If you do not specify an entry for form length, the default is 66 lines. 


To define the overflow line, you must make the following entries in the 
Line Counter specification: 


¢ Columns 20 through 22 (overflow line number)—specify the line 
number where an overflow occurs. 


¢ Columns 23 and 24 (OL)—if you specify an overflow line number in 
columns 20 through 22, you must enter OL in columns 23 and 24. 
This entry indicates to the compiler that columns 20 through 22 define | 
the overflow line number. 


If you do not specify an entry for the overflow line, the default is line 60. 


9.6 Spacing and Skipping Lines 


You can define how your printed output file will look by specifying the 
number of lines to space or skip. Spacing is relative to the line currently 
being printed; therefore, use spacing between detail lines in a report. 
Skipping lines repositions the printer to an absolute line number; there- 
fore, specify skipping for the column headers of a report. For example, 
if you specify skip to line number 2, the output line associated with that 
specification will be printed only on the second line of each page. 
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To specify the number of lines to space, you must make the following 
entries in the Output specification: 


¢ Column 17 (space before)—specifies the number of lines to be spaced 
before printing a line. 


e Column 18 (space after)—specifies the number of lines to be spaced 
after printing a line. 


To specify the number of lines to skip, you must make the following 
entries in the Output specification: 


* Columns 19 and 20 (skip before)—specifies the line number to‘skip to 
before printing a line. 

* Columns 21 and 22 (skip after)—specifies the line number to skip to 
after printing a line. 


If you make entries in both spacing and skipping columns for the same | 
line, VAX RPG II formats the output in the following order: 


1. Skip before 

Space before 

Print the output line 
Skip after 

Space after 


oe oe ee 


You can specify entries in columns 17 through 22 (space and skip) for the 
second line in an OR relationship; otherwise, the preceding line specifies 
the entries for spacing and skipping. 


NOTE 


If the line printer listing of a printer output file includes an 
unexpected blank page at the end of the file, use the DCL 
PRINT/NOFEED/PASSALL command. 
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The following example prints TOP on line 1, TEST LINE on line 7, PRINT 
TWICE FOR BOLDING on line 13, and the fields beginning on line 16. 


| name II| Format (PB) 
| | | 

AB A _NxxNXXNXx | Vil 

0 | 1 | é | 3 | 4 7 | 

123456 7890123456789012345678901234567890123456 7890123456 7890123456 7890123456 7830 


Type (HDTE) Edit codes , ONOCR - 
IFetch of] / Rel (FR) | X Sena aceon 
1 |Space 1 Y date edit YYiad 
I1l Skip | Z zero suppress Y N 2 B K 
Ht | l NY SCL 
ttl |) Indicators IBlank-after (B) N N 4 D M 
File tet | Field IlEnd position 
name ith | 
Ht 
118 


I+ Constant or edit word + . 









Tn % HER -— HE aoa 
QOUT92A H iP 

0 41 ’TOP’ 

0 H 320411 1P 

0 44 ’TEST LINE’ 

0 H 0 iP _ 

0 30 ’PRINT TWICE FOR BOLDING’ 
0 H {5 iP 
0 30 "PRINT TWICE FOR BOLDING’ 
0 Di NiP 

0 DESCR 18 

0 STOCKH 26 

0 ONHANDZ 34 

0 


PRICE KE 39 ’$’ 
Z2K-4422-85 
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Sample output from this example might look like the following: 


5 | 6 | 


12345678901234567890123456789012345678901234567890123456789012345678901 234567890 


0 | 1 2 | 3 | 4 
1 TOP 
2 
3 
4 
5 
6 
7 TEST LINE 
8 
9 
10 
11 
12 
13 PRINT TWICE FOR BOLDING 
14 
15 
16 1 LB CARROTS VEGiIMQ 47 # $.79 
17 6 PACK SODA DRNK2A 40 $1.48 
18 1 LB BUTTER DAROBT 38 $1.59 
19 STEAK METO 22 $3.15 
20 HEAD LETTUCE VEGiWQ 63 $.35 
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Chapter 10 


Using Tables 


In VAX RPG II, a table is a collection of similar data items arranged in a 
specific order. Each entry in a table must have the same length and the 
same data type (either character or numeric). There are two types of tables 
you can use to locate a specific data item quickly and easily. 


e Single tables—consist of one group of similar entries. When you 
search a single table, the result of the search is whether the item you 
are searching for is present in the table. If the searched-for item is 
found, that entry becomes the current entry. 


e Related tables—are two associated tables that can be entered in 
alternating format. You search the first table to find out if the entry is 
present. If the entry is found, VAX RPG II retrieves the corresponding 
entry from the second table. Related tables need not have the same 
number of entries unless they are described in alternating format in 
the same Extension specification. 


If you describe a table in alternating format, the first entry from the first 

table is read first; then, the first entry from the second table is read. This 
alternate reading continues until all entries from both tables are read. _ 

Together, the corresponding entries from each table form one record. For 
an example of alternating format using arrays, see Section 11.5.4. 


Types of tables are differentiated by whether they are loaded at compile 
time or preexecution time. Loading is the process by which the program 
assigns the data you supply to the elements in the table. 


The following characteristics determine when a table should be loaded: 


e The contents of a table . 
e The frequency with which the entries in the table require changing — 
e The way the table is to be used 
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10.1 Compile-Time Tables 


Compile-time tables are part of the source program. They are compiled 
with the source program and become a permanent part of the object 
program. The following example shows a source program and a compile- 
time table: 


) i | 2 | 3 | 4 | 5 | a) | 7 
123456789012345678901234567890123456 7890123456 7890123456789012345678901234567890 





FINPUT IPE F 30 DISK 
FREPORT O 40 DISK 
E TABA 10 50 5 
TINPUT AA Of 

I 


1 5 ITEM 
I 6 102FLD1 
I 45 30 FLD2 
C Ol ITEM LOKUPTABA 141 
C Nil SETON Hi 
C il 100 ADD FLD1 NEW 62 
0 


REPORT D O1 11 
0 NEW B 20 
// 


10001100021000310004100051000610007100081000910010 
20001200022000320004100052000610007200082000920010 
30001300023000330004100053000610007300083000930010 
40001400024000340004100054000610007400084000940010 
50001500025000350004100055000610007500085000950010 
/* 
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One advantage of compile-time tables is that they do not need to be 
loaded separately each time the program is run. However, if you need 

to change any of the entries in a compile-time table, you must revise the 
table and then recompile the program with the revised table. You can, 
however, make temporary changes in the table during calculations. To 
make these temporary changes permanent, you must output the table. See 
Section 10.8 for information about outputting tables. 


The data in a compile-time table must follow the source program and any 
alternate sequence records. 
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10.2 Preexecution-Time Tables 


Preexecution-time tables are not part of the object program; each table is 
loaded separately from an input data file. One advantage of preexecution- 
time tables is that you can make frequent changes to the table without 
recompiling the program. 


Preexecution-time tables are loaded before the first program cycle begins. 


10.3 Creating Table Input Records 


Table input records are the values for the entries in a table. When creating 
table input records, observe the following rules. 


General Rules 


The first entry must begin in character position 1. 


All entries must be contiguous, with no space between entries, as 
shown in Figure 10-1. 


You cannot span an entry across two records. Therefore, the length 
of a record is limited to the device’s maximum record length. If you 
use related tables in alternating format, corresponding records cannot 
exceed the maximum record length. . 


Each input record, except the last, must have the same number 
of entries. This record can be shorter to accommodate an uneven 
number of entries. 


Compile-Time Rules 


The first record must be preceded by a record containing either double 
slashes (//) and a blank or double asterisks (**) and a blank in 
character positions 1 through 3. Because these strings are delimiters, 
records in a compile-time table cannot contain either of these three 
characters in positions 1 through 3. 


The last record of the last compile-time table or array can be followed 
with a record containing a slash and an asterisk ( /*) in the first two 
character positions. This record is optional and must be the last record 
in the source program, if used. | 
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Figure 10-1: 


Table Input Record 


record 
/ entry entry entry entry entry \ 


/ \/ Ys V7 eA \ 


12345678901 
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234567890123456789012345678901234567890 —<_—_—_——— table 
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The table in Figure 10-1 consists of five entries in a record, and each entry 
is 10 characters long. 


When creating table input records for related preexecution-time and 
compile-time tables in alternating format, you must enter an entry from 
the first table and then follow with the corresponding entry from the 
second table. 


If you define each entry from the first table to be one character long and 
each entry from the second table to be three characters long, your table 
input record might appear as in Figure 10-2. 


Figure 10-2: Related Tables 


entry 


13331333133313331333 -«|_——_—— one record 


entry from second table 


entry from first table 
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The table in Figure 10-2 consists of fives entries in a record, and each 
entry consists of two related entries. The first entry is one character long. 
The second entry is three characters long. 


10.4 Defining Tables 


To define a single table, you must make the following entries in the 
Extension specification: 


Columns 27 through 32 (table name)—specify the name of the table. 
Table names can be up to six characters long, but the first three 
characters must be TAB. 


Columns 33 through 35 (entries per record)—specify the number of 
entries in a record. Because tables can have one or more entries for 
each record, calculate the maximum number of entries in a record by 
dividing the record length by the length of an entry. 


Columns 36 through 39 (number of entries per table)—specify the 
number of entries in the table. 

Columns 40 through 42 (length of entry)—specify the length of each 
entry. 

Column 43 (data format)—if the table contains numeric data, you 
must specify its format. Specify P (packed decimal format), B (binary 
format), or leave the entry blank (overpunched decimal format). 
When you specify packed decimal format, make sure the length of 
entry represents the length of the numeric data in unpacked form. 
When you specify binary format, the length of entry you specify must 
indicate the number of bytes required to store the binary field. (Use 4 
for two-byte signed binary numbers or 9 for four-byte signed binary 
numbers.) 


Column 44 (decimal positions)—for numeric data, specify the number 
of positions to the right of the decimal point. You must specify 0 for 
no Decimal positions. 


Column 45 (sequence)—specify ascending (A) or descending (D) to 
indicate that the entries in a table are in the specified sequence, or 
leave this column blank to specify an unsequenced table. 


There are additional considerations for compile-time tables and 
preexecution-time tables, which are discussed in Sections 10.4.1 
and 10.4.2. 
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10.4.1 Defining a Compile-Time Table 


To define a compile-time table, you must make the entries shown for any 
single table. There is one notable exception to the requirements shown in 
Section 10.4—columns 43 and 55 must be blank for a compile-time table 
because packed and binary data formats are not allowed in VAX RPG II 
program source code. 


In the following example, the table name is TABLE1. There are 10 entries 
in the table, with one entry in each record. The length of each entry is 
five digits, with two decimal positions. The data type of the entry in each 
record is overpunched numeric by default. 


Srs=s2 F = Format (PB) 

Lessa D = Decimal positions 

Il ----S = Sequence (AD) 

itl 

l}lAlternating table or array 
From To Table EntEnt LenlIIname Len . 
file file or perin of FIll of F 
name name array RecTbl EntiDII Ent ID 
| name | | I UISI 1 11S 

Vil 
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0 i | 2 
125456 7890123456 7890123456 7890123456 7890125456 7890123456 7890123456 7890125456 7890 


| 
| 3 | 4 | 5 | 6 | 7 | 


| I | 1 Itl+-- Comments -~-+ 








¥ ¥ HK —-——-H-—KKKE H-—-KHERE 
TABLE 1 10 52 
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You can define one or two tables either individually, or as a main table 
with an alternate table defined in alternating format. To define an alter- 
nate table, you must make the following entries for the alternate table in 
the same Extension specification you used to describe the main table: 


¢ Columns 46 through 51 (table name)—specify the name of the alter- 
nate table. Table names can be up to six characters long, but the first 
three characters must be TAB. 


¢ Columns 52 through 54 (length of entry)—specify the length of each 
entry in the alternate table. 


¢ Column 55 (data format)—if the alternate table contains numeric data, 
you must specify its format. Specify packed decimal format (P), binary 
format (B), or leave the entry blank (overpunched decimal format). 
When you specify packed decimal format, make sure the length of 
entry represents the length of the numeric data in unpacked form. 


When you specify binary format, the length of entry you specify must 
indicate the number of bytes required to store the binary field. (Use 4 
for two-byte signed binary numbers or 9 for four-byte signed binary 
numbers.) 


e Column 56 (decimal positions)—for numeric data, specify the number 
of positions to the right of the decimal point. You must specify 0 for 
no decimal positions. ) 


e Column 57 (sequence)—specify ascending (A) or descending (D) to 
indicate that the entries in a table are in the specified sequence, or 
leave this column blank to specify an unsequenced table. 


The main table’s values for entries per table (columns 36 through 39), 
from file name (columns 11 through 18), and entries per record (columns 
33 through 35) are also used for the alternate table. 


In the following example, two related tables are loaded from the input file 
INPUT. The second table, TAB2, is the alternate table. 


seated F = Format (PB) 
j Rese D = Decimal positions 
I! ----S = Sequence (AD) 
Ht 
ltlAlternating table or array 
From To Table EntEnt Leni|lIname Len 
file file or perin of FIII of F 
name name array RecTbl EntiDIi Ent ID 
| | name | | 11S f TIS 
Ht 


E | | | | | | f 


| [ll+-- Comments ---+ 





0 | 4 | 2 | 3 | 4 | 5. | ) | if | 
123456 7890123456 7890123456 7890123456 7890123456 7890123456 7890123456 7890123456 7890 
Hee % % H-—¥—— HK —-—KREKKEK H-—HKRKE 
E INPUT TABL 2 4 5 OATAB2 5 OA 
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When defining compile-time tables, observe the following rules. 


e If the compile-time table contains numeric data, it must be in over- 
punched format. Therefore, leave column 43 (data format) blank or 
leave column 55 (data format) blank, if you are using related tables in 
alternating format. 


e The input records for compile-time tables must be in the same order 
in which the tables appear in the Extension specification. 
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10.4.2 Defining a Preexecution-Time Table 


To define a preexecution-time table, make the same entries you made for 
a single table as in Section 10.4. In addition, in columns 11 through 18 
(from file name), enter the name of the input file that contains the data for 
the table, as shown in the following example: 





Seecc= F = Format (PB) 
Peeae D = Decimal positions 
1| ----S = Sequence (AD) 
Hl 
{i lAlternating table or array 
From To Table EntEnt Lenlilname Len 
file file or perin of Fill of F 
name name array RecTb! EntiDl| Ent iD 
| } name | | | IISI 1 tS 
E | I | 1 ot of tll | I1l+-- Comments ---+ 
0) | 3 4 5 6 7 
Se ee 
Heeea® ¥ aah RRR KEE H--KERK 
E INPUTFIL TABLEA 10 50 5 
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The table input file must be defined in a File Description specification by 
specifying T in column 16 (file designation). 


When using preexecution-time tables, observe the following rules. 


e The input file cannot contain more entries than are defined for the 
table. If it does, a run-time error occurs. 


e The input file can contain fewer entries than are defined for the table, 
only if you do not specify a sequence. When you do not specify a 
sequence and the table contains fewer entries than are defined, the 
remaining entries are automatically filled with blanks for character 


data or zeros for numeric data. 
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10.5 Referencing Table Entries 


When you use a table name as an operand other than as factor 2 in an 
operation or other than as the result field in a LOKUP operation, the table 
name refers to the data retrieved by the last successful search. You can 
then use the entry as an operand in a calculation or modify the contents of 
the entry when the table name is used as the result field in a calculation. 


In the following example, FLD1 is the search argument in the LOKUP 
operation. If the program can locate FLD1 in TAB1, indicator 10 is set on. 
Then, the result of the calculation on the next line replaces the current 
contents of the located entry in TAB1 because the table entry is used as 
the result field. 


Field length 


Control level | Decimal positions 
| | IHalf adjust (H) 
| Indicators Operation 1 ot 
1 | | Resulting 
1 | ~ Factor | Factor Result! Illindicators 
1 | { | 2 field | Il+- 0 
Cl NxxXNxXxNXx! | | | | I> < = +- Comments --+ 





2 | 3 | 4 | 5 | 6 I 7 | 
123456789012345678901234567890123456 7890123456 7890123456789012345678901234567890 
RK KecenncceMeccnccvcekeccekecncceceskasras eMr~mRRE HH Ke ence ceeanesevareeesr 
¢ FLDi = LOKUPTAB4 10 
C TABI MULT 100 TABL 
ZK-4426-85 


You can specify which entry is the current entry for related tables and then 
reference the current entry in subsequent calculations. In the following 
example, FLD1 is the search argument in the LOKUP operation. If the 
program locates FLD1 in TAB1, that entry becomes the current entry. 
Then, VAX RPG II locates the corresponding entry in TAB2 and it then 
becomes the current entry for TAB2. When you reference these entries in 
subsequent calculations, VAX RPG II uses the current entry in both tables. 
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Field length 


Control level | Decimal positions 
| | {Half adjust (H) 
| Indicators Operation 1 od 
1 | | | JlResulting 
14 Factor | Factor Result! Jlindicators 
1 | | | 2 field | Il+- 90 
Cl NxxNxxNxxt | | | | Jl> < = +- Comments --+ 
2 3 I 4 | 5 | 6 | 7 
123456789012345678901234567890123456 78901234567890123456789012345678901234567890 
ee eee 
C FLD4 LOKUPTAB1 TAB2 10 
ZK-4427-85 


10.6 Searching Tables 


The LOKUP operation code searches for an entry in a table. This opera- 
tion starts with the first entry and searches each element for a match with 
the search argument. Specifying a table sequence is not necessary when 
performing LOKUP operations for an equal match. However, if you spec- 
ify a sequence, the table can be searched faster. To save time in searching 
an unsequenced table, place the more frequently referenced entries at the 
beginning of the table. 


To search a table for an entry, you must make the following entries in the 
Calculation specification: 


10-10 Using Tables 


Columns 18 through 27 (factor 1)—specify a field or literal repre- 
senting the entry you want to locate. Make sure the search argument 
has the same length and data format as the entries of the table being 
searched. 


Columns 28 through 32 (operation code)—specify the LOKUP opera- 
tion code. 


Columns 33 through 42 (factor 2)—specify the name of the table to be 
searched. 


Columns 54 through 59 (resulting indicator)—specify one or more in- 
dicators to condition the search and to indicate whether the search has 
been successful. You can use this indicator to condition subsequent 
calculation and output operations. 


In the following example, the program tries to match the search argument 
ITEM with an entry in table TABA. If a matching entry is found, indicator 
11 is set on. If no matching entry is found, the halt indicator H1 is set on 
and the program terminates. 





0 { | 2 3 4 | 5 | 6 | ri | 
{ 23456 7890123456 7890123456 7890123456 7890123456 789012345678901 23456 78901234567890 


FINPUT IPE F 30 DISK 

FREPORT 0 40 DISK 

E TABR 10 50 5 

IINPUT AA Of 

I 4 5 ITEN 
I 6 102FLD1 
I . {5 30 FLD2 
c «(Of ITEM LOKUPTABA 11 
C Nid SETON Hi 
Cc if 100 ADD FLDI NEW 62 
OREPORT oD 01 i1 

0 NEW B 20 


// 

10001100021000310004100051000610007100081000910010 

20001200022000320004100052000610007200082000920010 

30001300023000330004100053000610007300083000930010 

40001400024000340004100054000610007400084000940010 

Fa a ct a al al 
¥ i 
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In this compile-time table, there are 10 entries in a record and 50 entries 
in a table. Each entry is five characters long. 


When you specify a sequence (either ascending or descending), you can 
use resulting indicators (EQUAL, HIGH, and LOW) in the Calculation 
specification to indicate the condition to search for and the result of the 
search. You can specify one of the following search conditions: 


e Columns 54 and 55 (HIGH)—nearest to but greater than value only 


¢ Columns 56 and 57 (LOW)—nearest to but less than value only 


-® Columns 54 and 55, and 58 and 59 (EQUAL or HIGH)—equal or 
nearest to but greater than value 


¢ Columns 56 and 57, and 58 and 59 (EQUAL or LOW)—equal or 
nearest to but less than value 
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The following program searches the unsequenced table TABLE2 for the 
value LENGTH and searches the sequenced table TABLE1 to check for a 
value greater than or equal to COST. If both conditions are satisfied, the 
subroutine PROCES is called to process the entry. 





ores See | 2 3 | 4 | 5 6 7 
123456 78901234567890123456 7890123456 7890123456 7890123456 7890123456 78901234567890 
nn ee en Se es ae ae 

FFILEA IT F 80 80 EDISK 

FFILE2 IT F 80 80 EDISK 

FINFILE IP F 80 80 DISK 

E FILE4 TABLE 1 6 3 2A 

E FILE2 TABLE2 1 6 30 

TINFILE AA if 

I i 3e2c0sT 

I 4  60LENGTH 
I 7 400NUMBER 
¢ if LENGTH LOKUPTABLE2 20 
C Neo if GOTO NOPROC 

c ff COST LOKUPTABLE1 26 26 
C N26 GOTO NOPROC 

C EXSR PROCES 

C NOPROC TAG 
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You can also specify a table in the result field to retrieve the entry that 
corresponds to the entry located in a LOKUP operation. See the example 
in Section 10.6 for an example of the LOKUP operation. 


10.7 Updating Tables 


To change the contents of an entry in, or add new entries to, a preexecu- 
tion table, edit the input file that contains the table. You can also use a 
program to modify a table and output the new entries. 


The following example searches related tables in alternating format. The 
first table, TABA, consists of a list of numbers of items in stock. The 
second table, TABB, consists of a list of unit prices corresponding to the 
item numbers. We want to raise the unit price of each item by 5% and 
output the updated table. 
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0 | 1 | 2 3 | 4 | 4) | 6 | ri | 
12345678901 2345678901 23456789012345678901234567890123456789012345678901234567890 





x* HEREH HK x HRR——— HK 
FMASTER IPE F 30 DISK 
FTABLE1 IT F 22 EDISK 
FTABLE2 O F 22 DISK 
FREPORT O F 60 DISK 


E TABLE{ TABLE2 TABA 2 10 5 TABB 62 
IMASTER AA Of 
I 


1 5 ITEM 
Cc Of ITEM LOKUPTABA TABB 41 
C Nii SETON Hi 
Cc ff 1.05 MULT TABB TABB 62H 


OREPORT D 41 
0 TABB 20 
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The related tables, TABA and TABB, are preexecution-time tables. They 
are loaded from the input table file TABLE1. In the Extension specification, 
the output file TABLE2 is automatically created. (Automatic creation 
means that the output file does not require an Output specification.) 


When the program executes, it reads the first record from the primary 
input file MASTER. If the search argument ITEM is matched, indicator 11 
is set on and the corresponding entry from TABB is made available for 
processing. If no match is found, the halt indicator H1 is set on and the 
program terminates without creating the output file TABLE2. 


When the program ends, the tables TABA and TABB are written to file 
TABLE2 with the same number of entries per record as the table input file 
TABLE1. 


10.8 Outputting Tables 


When you specify the name of an output file in columns 19 through 26 
(to file name) of the Extension specification, your program creates the file 
automatically, as shown in the example in Section 10.7. 


When you specify a table as a field on an Output specification, you can 
output only the entry found by the last LOKUP operation. 
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In the following example, the table TABSH is read from the file TABFILE. 
For this example, the table is short; that is, not all 80 entries contain data.., 
The LOKUP operation searches the table for the first entry containing 
zeros. This entry is replaced with a field read from the input file IFILE. 
The EXCPT operation code outputs the entry TABSH with the new data. 
Remember, the entry that is updated and then output by the Output 
specification is the entry found by the last LOKUP operation. When 
the last cycle occurs, the entire updated table will be written to the file 
TABFILE2. 





Pe EE eT SE eal eae PS SEW a 
123456 78901234567890123456789012345678901234567890123456789012345678901 234567830 
FIFILE IP F 80 DISK 
FTABFILE IT F 80 EDISK 
FTABFILE20 F 80 DISK 
FOFILE O F B0 DISK 


E TABFILE TABFILE2TABSH 10 80 40 
IIFILE AA Of 
I 


{ 40ENTRY 
Cc «(Of 0000 LOKUPTABSH 20 
C O01 20 Z-ADDENTRY TABSH 
C O01 20 EXCPT 
QOFILE 
0 TABSH 10 
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Chapter 11 


Using Arrays 


In VAX RPG II, an array, like a table, is a collection of similar data items 
arranged in a specific order. You can reference individual array elements 
(entries) by specifying an array index, or process an entire array by 
specifying the array name during calculation operations. 


You use an array instead of a table when you want to affect all the 
elements in the array with a single reference or be able to reference a 
specified number of separate elements at the same time. For example, 
when you want to compute a 5% sales tax for each element in an array, 
you use a single specification to perform the operation for every element. 


Types of arrays are differentiated by whether they are loaded at compile 
time, preexecution time, or execution (run) time. Loading is the process 
by which the program assigns the data you specify to the elements in an 
array. 


The following characteristics determine when an array should be loaded: 


e The contents of an array 
¢ The frequency with which the elements in the array require changing 
e The way the array is to be used 
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11.1 Compile-Time Arrays 
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Compile-time arrays are part of the source program. They are compiled 
with the source program and become a permanent part of the object 
program. One advantage of compile-time arrays is that they do not need 
to be loaded separately each time the program is run. However, if you 
need to change any of the entries in a compile-time array, you must revise 
the array and then recompile the program with the revised array. You 
can, however, make temporary changes in the array during calculation 
operations. To make these temporary changes permanent, you must 
output the array and then, using the output file as input, recompile the 
program. See Section 11.10 for information about outputting arrays. 


When you use a compile-time array, the array input data must follow the 
source program and any alternate sequence (ALTSEQ) records. If you 
use more than one array, the data for each array must follow in the same 
sequence as specified on the Extension specifications. 


The following example shows a source program with the input data 
for two compile-time arrays and their alternate compile-time arrays. 





01010H 
OL040FPROCD IP F 80 
QL050FINLIST 0 F 132 OF 
02010E ARL 4 
02020E AR2 4 
030{01PROCD 
030201 
030301 
04010C 
04020C 
04030C 
04040C 
040500 24 QUAN 
OSO{00INLIST H 201 4P 
050200 OR OF 
020300 | 
050400 

050500 

050600 H 4 4P 
050700 OR OF 
050800 

050900 | 

051000 H 2  4P 
051100 OR OF 
051200 

051300 

051400 

060100 D4 Of 
060200 

060300 20 
060400 N20 
060450 24 
060500 

060700 N24 
060800 24 
060900 T1 LR 
061000 

4K 

17526BOLT 

18171SCREW 

19226NAIL 

25L16NUT 
29258MAGNESIUM COVER 

RK ; 


175260126181710059192260173292585843 
/* 


AA O41 


Z-ADD1 
LOKUPARA, I 
Z-ADD1 
LOKUPAR2, T 
MULT ALT2,T 


PRODNO 
PRODNO 


UDATE 
PAGE 


PRODNO 
ALT1i,I 


ALT2,T 
QUAN 


ANT 


0 | i | rs | 3 1 4 | 5 | 6 | 7 
12345678901234567890123456 7890123456 7890123456 789012345678901 2345678901234567890 


DISK 
PRINTER 
5 5 OAALT 20 
4 5 OAALT 


I 
T 





NOPRIN 
NOPRIN 
NOPRIN 
NOPRIN 


NOPDAT 


42 


1 5OPRODNO 
6  80QUAN 
20 
20 


24 


20 


AMT 72 


18 
47 
65 


32 
53 


17 
45 
64 


16 
39 


53 
45 


65 
et 


f / / ? 


"INVENTORY PARTS LIST’ 
? 0 ? 


"PRODUCT 
"UNIT’ 


PRODUCT’ 


"NUMBER ’ 
"DESCRIPTION 
"PRICE AMOUNT ’ 


QTY’ 


? 0’ 
*###NO DESCRIPTIONR#’” 
? 0 ? 


f O7 
"NONE 


"END OF PRICE LIST’ 


compile-time array ARI 
and the alternate compile-time 
array ALT1 


compile-time array AR2 and 
the alternate compile-time 
array ALT2 
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11.2 Preexecution-Time Arrays 


Preexecution-time arrays are not part of the object program; each array 
is loaded separately and is used like an input data file. One advantage 
of preexecution-time arrays is that you can make frequent changes to the 
array without recompiling the program. 


11.3 Execution-Time Arrays 


Execution-time arrays are created by using Input or Calculation specifica- 
tions. These arrays are loaded either from input data or as the result of 
calculation operations after program execution begins. 


11.4 Creating Array Input Records 


11-4 Using Arrays 


When creating array input records for compile-time and preexecution-time 
arrays, observe the following rules. 3 


General Rules 


e The first entry must begin in character position 1; all entries must be 
contiguous, with no space between entries, as shown in Figure 11-1. 


e You cannot span an entry across two records. Therefore, the length 
of a record is limited to the device’s maximum record length. If you 
use related arrays in alternating format, corresponding entries cannot 
exceed the maximum record length. 


e Each array input record, except the last, must have the same number 
of entries. This record can be shorter to accommodate an uneven 
number of entries. 


The array in Figure 11-1 consists of five entries, and each entry is 10 
characters long. 


Figure 11-1: Array Input Record 


y 


12345678901234567890123456789012345678901234567890 ———— array 


entry 
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When creating compile-time array input records, observe the following 
rules. 


Compile-Time Rules 


e The first record must be preceded by a record containing either double 
slashes (//) and a blank or double asterisks (**) and a blank in 
character positions 1 through 3. Because these strings are delimiters, 
compile-time array records cannot contain either of these characters in 
positions 1 through 3. 


e The last record of the last compile-time table or array can be followed 
by a record containing a slash and an asterisk ( /*) in the first two 
character positions. This record is optional and must be the last record 
in the source program, if used. 


When creating array input records for related preexecution-time and 
compile-time arrays in alternating format, you must enter an entry from 
the first array and then follow with the corresponding entry from the 
second array. 


If you define each entry from the first array to be one character long and 
each entry from the second array to be three characters long, your array 
input record might appear as in Figure 11-2. 
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Figure 11-2: Related Arrays 


entry 


12221222122212221222 -~—«_|£t—— one record 


entry from second array 


entry from first array 
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The array in Figure 11-2 consists of five entries in a record, and each entry 
consists of two related entries. The first entry is one character long. The 
second entry is three characters long. 


11.5 Defining Arrays 


11-6 Using Arrays 


To define an array, you must make the following entries in the Extension 
specification: 


Columns 27 through 32 (array name)—specify the name of the array. 
You cannot use TAB as the first three letters of an array name. 


Columns 36 through 39 (number of entries per array)—specify the 
number of entries in the array. 


Columns 40 through 42 (length of entry)—specify the length of each 
entry. 


Column 44 (decimal positions)—for numeric data, specify the number 
of positions to the right of the decimal point. You must specify 0 for 
no decimal positions. 


Column 45 (sequence)—specify ascending (A) or descending (D) to 
indicate that the entries in an array are in the specified sequence, or 
leave this column blank to specify an unsequenced array. 


11.5.1 Defining a Compile-Time Array 


To define a compile-time array, you must make the following entry in the 
Extension specification in addition to the entries required for all arrays: 


¢ Columns 33 through 35 (entries for each record)—specify the number 
of entries in a record. Arrays can have one or more entries per record. 
The length of all entries in a compile-time array cannot exceed 96 
characters. All records, except the last, must contain the same number 
of entries; each entry must be the same length. 


The following example describes the compile-time array Al. The array _ 
has eight entries with four entries in each record. Each entry is a character 
field that is six bytes long. The array records are located at the end of the 





program. 
ear F = Format (PB) 
[Losesee D = Decimal positions 
1! ----§ = Sequence (AD) 
I 
[1 lAlternating table or array 
From To Table EntEnt Lenll!name Len 
file file or perin of Fill of F 
name name array RecTbl EntiDI| EntID 
| | name | | | ISI 1 tS 
E. | } 1. 1 | 1 itl | Jil+-- Comments ---+ 
4 
Heaaek * # rer TTT ee oe 
Al 4 8 6 


#¥ 


KAUNISKAUPPANAINENKAIEKI 
MUKAVAPALJONJUUSTOOSOITE 
/* | 
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11.5.2 Defining a Preexecution-Time Array 
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To define a preexecution-time array, you must make the following entries 
in the Extension specification in addition to the entries required for all 
arrays: 


¢ Columns 11 through 18 (from file name)—specify the name of the 
input file that contains the data for the array. This input file is called 
a table input file. It must be defined in a File Description specification 
by specifying T in column 16 (File designation); the T associates the 
file with the array. 


© Columns 33 through 35 (entries per record)—specify the number of 


entries in a record. Arrays can have one or more entries per record. 
The length of all entries in a preexecution-time array cannot exceed 
the maximum number of characters for the device from which the 
array is loaded. All records except the last must contain the same 
number of entries; each entry must be the same length. 


If your preexecution-time array contains numeric data, you can indicate 
the data format by specifying packed decimal format (P) or binary format 
(B), or by leaving the column blank (overpunched decimal format). When 
you specify packed decimal format, make sure the length of entry repre- 
sents the length of the numeric data in unpacked form. When you specify 
binary format, the length of entry you specify must indicate the number of 
bytes required to store the binary field. (Use 4 for two-byte signed binary 
numbers or 9 for four-byte signed binary numbers.) 


When using preexecution-time arrays, observe the following rules. 


e The input file cannot contain more entries than are defined for the 
array. If it does, a run-time error occurs. 


e The input file can contain fewer entries than are defined for the array, 


but only if you do not specify a sequence. When you do not specify 
a sequence and the array contains fewer entries than are defined, 
the remaining entries are automatically filled, either with blanks for 
alphanumeric data or with zeros for numeric data. 


11.5.3 Defining an Execution-Time Array 


To define an execution-time array, the number of entries that must be 
made in the Extension specification is the same as that required for all 
arrays. 


If you want to load an execution-time array from an input file, you must 
make the following entries for the array input file in its Input specification: 


¢ Column 43 (data format)—if the array contains numeric data, indicate 
the data format by specifying packed decimal format (P) or binary 
format (B), or by leaving the entry blank (overpunched decimal 
format). 


¢ Columns 44 through 51 (field location)—specify the beginning and 
ending character positions of the entire array, partial array, or array 
element being loaded. If the data format is packed decimal or binary, 
the field location must represent the actual size of an array element in 
bytes. 


The following example shows how to use the Input specification to load 
an entire execution-time array containing packed decimal numbers as a 
single field. Array ARR contains seven elements, and each element is four 
bytes long. The execution-time array is loaded from the input file ARRIN | 
as a single field in packed decimal format. 


MS Sale ier bo 


) | 4 | fe | 3 | 4 
123456 7890123456789012345678901234567890125456 7890123456 789012345678901234567890 





ARR 7 790 


E 
IARRIN AA 03 
I P 1 280ARR 
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You can load part of an execution-time array using one input field. The 
length of the field must be a multiple of the length of one entry. The 


array is loaded beginning with the first element and entries continue to be 
loaded until the end of the input field is reached. 
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In the following example, ARR contains 25 entries. Each entry is one 
character long. VAX RPG II loads the first 10 elements of the array ARR. 


eee ee tae oe bee Be | 





Pa 4 
CRLOCIEL ERC RCVELISERL GYELUSERCOCIECISER, GLUYECUSERS GCVECUSER, GCPALIS ERE GREE) 


E ARR 25 i 
IARRIN AA 03 
I 4 100ARR 
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11.5.4 Defining Related Arrays in Alternating Format 


You can define related arrays either individually or in alternating format. 
To define arrays in alternating format, you must make the following 
entries for the second (alternate) array in the same Extension specification 
you used to describe the first (main) array: 


¢ Columns 46 through 51 (array name)—specify the name of the 
alternate array. 


e Columns 52 through 54 (length of entry)—specify the length of an 
entry in the alternate array. 


¢ Column 55 (data format)—you need only specify the data format 
for alternate preexecution-time arrays that contain numeric data. 
Specify packed decimal format (P) or binary format (B), or leave the 
entry blank (overpunched decimal format). When you specify packed 
decimal format, make sure the length of entry represents the length of 
the numeric data in unpacked form. When you specify binary format, 
the length of entry you specify indicates the number of bytes required 
to store the binary field. (Use 4 for two-byte signed binary numbers 
or 9 for four-byte signed binary numbers.) 


¢ Column 56 (decimal positions)—for numeric data, specify the number 
of positions to the right of the decimal point. You must specify 0 for 
no decimal positions. 


e Column 57 (sequence)—to indicate that the order of entries in an 
alternate array are in the specified sequence, specify either ascend- 
ing (A) or descending (D) or leave this column blank to specify an 
unsequenced array. 
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The entries made in the following columns for the main array also apply 
to the alternate array: 


¢ Columns 11 through 18 (from file name) 
e Columns 33 through 35 (entries per record) 
e Columns 36 through 39 (entries in array) 


The following example describes the preexecution-time array Al with 6 
entries in each record and 24 entries in the array. The entries for array 
A1 are alternated with entries for array B1. Al contains overpunched 
numeric data that is six digits long with no decimal places. B1 contains 
overpunched numeric data that is six digits long with two decimal places. 
Each record in the data file contains six entries for Al and six entries for 
B1. The arrays are loaded from the file ARRFIL. 





soma — F = Format (PB) 
| Sees= D = Decimal positions 
11 ----S = Sequence (AD) 
It 
. 1tlAlternating table or array 
From To Table EntEnt Lenl|lIname Len 
file file or  perin of FIII of F 
nane name array RecTbl EntiDI1 Ent iD 
| | name | | ff IISI 1 1S 
E | I | ee ee ee | {ll+-- Comments ---+ 
| 4 
{ 
#...0% x x H—--H--—-H--KRHKE H-- HEHE 
E ARRF IL Al 6 24 60 Bi 42 
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A sample record from ARRFIL might look like this: 


000001245000000216240000034520000004799000000577770000066550 
\ IN IN IN / 


| | | | 
Ai,i Bi,1 A1,2 B1i,2. . 
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11.6 Referencing Arrays 


With tables, you can reference only the entry retrieved by the last LOKUP | 
operation. With arrays, you can refer to either an entire array or an 
individual array element. One advantage of referencing an entire array is 
that a single operation can affect all the elements in the array. 


You can specify an array name, a comma, and an index up to 10 characters 
long for factor 1 or factor 2 in a Calculation specification. You can specify 
an array element up to six characters long for the result field. 


You can use an entire array as factor 1, factor 2, or the result field in the 
following operations: 


¢ ADD 
° Z-ADD 
° SUB 

¢  Z-SUB 
° MULT 
° DIV 

© SORT 

°¢ MOVE 
© MOVEL 
© MOVEA 
° XFOOT 
° LOKUP 
¢ PARM 


When you specify an array name in the following calculations, 
VAX RPG II repeats the operation for each element in the array: 


e ADD 

e Z-ADD 
e SUB 

e Z-SUB 
¢ MULT 
e DIV 

¢ SQRT 
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MOVE 
MOVEL 


When using entire arrays (nonindexed) in any calculations, observe the 
following rules. 


When you specify arrays with the same number of elements for factor 
1, factor 2, and the result field, VAX RPG II performs the operation on 
the first element, then on the second element, and so on, until all the 
elements in the array have been processed. 


If the arrays do not have the same number of elements, VAX RPG II 
ends the operation when the last element of the array with the fewest 
elements is processed. 


When one factor is a field or constant and the other factor or result 
field is an entire array, VAX RPG II performs the operation once for 
every element in the array. 


If the operation requires factor 2 only and the result field is an array, 
VAX RPG II performs the operation once for every element in the 
array. 


You must specify an array for the result field. 


You cannot use resulting indicators to condition calculations with 
arrays. 


If you use an array for the result field and an element as one of the factors 
in a calculation, VAX RPG II alters the value of the element as a result 

of the calculation. When this occurs, VAX RPG II uses the new value in 
all subsequent operations that reference that element. For example, two 
numeric arrays contain the data shown in Table 11-1. | 
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Table 11-1: Array Element Values 


Array Element Value 
ARR1,1 4 
ARR1,2 3 
ARR1,3 1 
ARR1,4 5 
ARR2,1 2 
ARR2,2 7 
ARR2,3 5 
ARR2,4 9 


If every element of ARR1 is added to element ARR2,3 and the result 
is placed in ARR2, the elements of the resulting array are as shown in 
Table 11-2. 


Table 11-2: Array Elements in Calculations 


Array Element Expression Resulting Value 
ARR2,1 (4 + 5) ] 

ARR2,2 (3 + 5) 8 

ARR2,3 (1 + 5) 6 

ARR2,4 (5 + 5) 10 


You can specify an array element in most operations that take a character 
or numeric field as factor 1, factor 2, or the result field. To specify an 
individual array element, enter the array name, a comma, and the index. 
For example, ARR,12 specifies the twelfth element of array ARR. You can 
also use a field name to represent the index. For example, if you specify 
ARR,FLD, the index value is determined by the value of the field FLD. 


An array index, whether it is a literal or a field, must always be greater 
than or equal to 1 and less than or equal to the number of elements in 
the array. If it is not and you specify the / CHECK=(BOUNDS) qualifier 
to the RPG command, a run-time error will occur. If it is not and you 
do not specify the /CHECK=(BOUNDS) qualifier to the RPG command, 
unpredictable results will occur. 


11-14 Using Arrays 


If you plan to use the same array element in a calculation for every 
program cycle, use a constant number as the index. If, however, you want 
- to reference different array elements, use a field name as the index. 


When array elements are scattered throughout an input record, each 
field must be described individually on the Input specification. A field 
description indicates the position of an element in the array. In such 
cases, there are two ways to load the data into the array: 


e Assign a unique field name-to each field of array data on the input 
record and then enter calculations to move individually each data field 
into the appropriate array element. 


e Assign the array name with the proper index to each field of array 
data in the input record. The array is loaded automatically as the data 
is read. 


The following example shows how to load individually each element of 
an execution-time array: 










| 
0 





0 | i I 2 3 | 4 | al a) | 7 
123456789012345678901234567890123456 7890123456 7890123456 7890123456 7890123456789 


E ARR 70 

IARRIN AA 03 

I P i = 40ARR, 1 
I P 5  80ARR,2 
I P 9 120ARR, 3 
I P 13 460ARR,4 
I P 17 200ARR,5 
I P 241 240ARR,6 
I P 25 280ARR,7 
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In the following example, a company employs eight sales people whose 
weekly sales amounts are recorded in an input file. Each record of the file 
contains the weekly sales amounts; one new record is recorded in the file 
each week. At the end of the year, the company generates a report listing 
the sales totals for each week and the grand total for the entire year. 
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A) | 4 | 2 | 3 | 4 | 5 | 3) | ri 
123456 7890123456 7890123456 789012345678901234567890123456 7890123456 78901234567890 


FINPUT1 
FREPORT 
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I 


C (Of 
Cc O04 
CLR 
OREPORT 
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IPE F 60 DISK 
0 6F 60 DISK 
WEEK 8 6 2 
YEAR 8 8 2 
AA O1 
1 482WEEK 
XFOOTWEEK. TOTAL 82 
WEEK ADD YEAR YEAR 
XFOOTYEAR GRAND 102 
D 01 


20 "WEEKLY TOTAL=’ 
TOTAL g's , . ° 
T LR 
20 "YEARLY TOTAL=’ 
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Two execution-time arrays, WEEK and YEAR, are defined in the Extension 
specification. The Input specification instructs the program to load the 
array WEEK after reading each sales record from the input file INPUT1. 


The input file for the execution-time array is not like a table input file 
with a corresponding File Description specification. Therefore, data is not 
automatically loaded into the array at the beginning of execution. Instead, 
you must describe on Input specifications the input data to be loaded into 
the array. 


The array elements are in contiguous positions in the input record. 
Therefore, when the name of the array is specified as the field name, 

the data is automatically loaded into the appropriate elements of the array 
as the input record is read. In this case, only one Input specification is 
necessary to describe an input record of array data. 


The XFOOT operation calculates the sum of all the elements in the array 
WEEK and puts the sum in the result field TOTAL. The next calculation 
adds one array to the other. Adding arrays involves adding each element 
of one array to the corresponding element of the other array. Normally, 
when you use an array name in a calculation, the operation is performed 
on each element of the array; then, an array of the results is created. 
Therefore, you cannot use resulting indicators to indicate the result of the 
operation. 
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These arrays have the same number of elements; therefore, any specified © 
operation is performed until all elements have been processed. In the 
case of two arrays containing different numbers of elements, the specified 
operation is performed only until the last element in the shorter array is 
processed. 


In the following example, the program produces results identical to those 
of the previous example. However, here the array elements are scattered 
throughout the input record. 





0 | | 2 3 4 | 5 6 | 7 
123456789012345678901234567890123456 7890123456 7890123456 789012345678901234567890 

FINPUT2 IPE F 60 DISK 

FREPORT QO F 60 DISK 

E WEEK 8 6 2 

E YEAR 8 8 2 
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Cc Of XFOOTWEEF TOTAL 82 

Cc O01 WEEK ADD YEAR YEAR 
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0 20 WEEKLY TOTAL=’ 
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0 T LR 

0 20 “YEARLY TOTAL=’ 
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11.7 Searching Arrays 


The LOKUP operation code searches for an element in an array. To 
determine whether a particular element exists, you specify a search 
argument and define the conditions under which the LOKUP operation 
will succeed. You must also use a resulting indicator that specifies the 
condition and that will indicate the result of the LOKUP operation. The 
indicator is set on only if the search is successful; otherwise, the indicator 
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is set off. When searching for a HIGH or LOW condition, you must 
specify a sequence for the array in column 45 (sequence) of the Extension 
specification. Enter an indicator in these columns to test for the following 
conditions: 

° Columns 58 and 59 (EQUAL)—equal 

e Columns 54 and 55 (HIGH)—nearest to but greater than value 

e Columns 56 and 57 (LOW)—nearest to but less than value 


e Columns 54.and 55, and 58 and 59 (EQUAL or HIGH)—equal or 
nearest to but greater than value 


e Columns 56 and 57, and 58 and 59 (EQUAL or LOW)—equal or 
nearest to but less than value 


If you specify both EQUAL and HIGH or EQUAL and LOW, the EQUAL 
condition takes precedence if entries satisfy both conditions. 


To search an array for an element, you must make the following entries in 
the Calculation specification: 


e Columns 18 through 27 (factor 1)—specify a field, literal, array 
element, or table representing the element you want to locate. Make 
sure the search argument has the same length and data format as the 
elements in the array being searched. 


e Columns 28 through 32 (operation code)—specify the LOKUP opera- 
tion code. 


e Columns 33 through 42 (factor 2)—specify the name of the array to 
be searched. 


¢ Columns 54 through 59 (resulting indicator)—specify one or more 
indicators to test for a condition and to indicate whether the search has 
been successful. You can use these indicators to condition subsequent 
calculation and output operations. 


In the following example, the program tries to match the search argument 


QTY with an entry in the array ARR. If a matching entry is found, 
indicator 11 is set on. If the entry is not found, indicator 11 is set off. 
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| Field length 
Control level | Decimal positions 
| 


[Half adjust (H) 





| 
| In dicators Operation 1 dl 
1 | | . | IlResulting 
1 | Factor | Factor Result! Illindicators 
of. | 2 field | Il+- 0 
Cl NocxNxxNo | = tok ca, _ 11s < =-+- Comments --+ 
0 4 2 3 4 | 5 | 6 1° 7 
CISL UNL AE CEL CE EE EE IE LE 
XK # ¥ # % H--#RE HH 
Cc «(Of aTy LOKUPARR . 14 
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If you want to start searching an array at some point other than at the 
beginning, specify the array and its index where you begin the search. 
The index can be a literal or a field name. In the following example, the 
search begins with the seventh element of array ARR: 


Field length 
Control level | Decimal positions 
| 


lHalf adjust (H) 





| 
| Indicators Operation | dl . 
1 | ; | | ItResulting 
1 | Factor | Factor Result! Ilindicators 
1 | { | 2 field | lit - 0 6 le 
Cl NxxNxxNdxX | — 4 A (eins | i> < = +- Comments --+ | 
| 2 | 3 | 4 | 5 | 3) | 7 | 
123456 78901234567890123456 7890123456 7890123456 7890123456 7890125456 78901234567890 
H% % % % % % H--HKE KK * 
C «(Of QTY LOKUPARR, 7 44 
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If you want to reference the element found in the last LOKUP operation, 
specify the array name and an index field in factor 2 of the LOKUP 
operation. If the search is successful, the index value of the array element 
that satisfied the condition is stored in the index field and the resulting 
indicator is set on. If the search is unsuccessful, the value 1 is placed 

in the index field and the resulting indicator is set off. If you do not 
specify the index field, a successful LOKUP operation indicates whether 
an element contains the data for which you are searching, but does not 
return the element's index value. 


If you want to begin the search with the first element, you must initialize 
the index field to 1 before the LOKUP operation occurs. 
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You can also search for more than one array element by locating all the 
elements in an array that satisfy a certain condition. When the condition 
is satisfied, the program adds 1 to the value in the index field to continue 
the search with the next element. 


In the following example: 


The program loads a preexecution-time array from the file INPUT1. 
The search argument SEARCH contains the value 50000; the LOKUP 
operation searches for any array element containing a value lower 
than the search argument. 

If the search is successful, indicator 56 is set on. This indicator causes 


the EXCPT operation to print the contents of each array element (and 
its index) that satisfies the search condition. 


After the program prints the array element, it sets indicator 56 off and 
adds 1 to the field containing the array index. While the index field 
remains below 11, the search continues by setting indicator 54 on; this 
causes the program to loop back to line 01090. This process continues 
until all 10 elements are searched. 





0 | 2 3 4 | 5 6 7 | 
12345678901 2345678901 23456 7890123456 78901254567890123456 7890123456 78901234567890 
O1020FINPUT1 IT F 50 EDISK 
OL1030FINPUT2 IPE F 10 DISK 
O2040FOUTPUT O F 60 DISK 
O1050E INPUT4 ARYL 10 10 5 OD 
OL060IINPUT2 AA O14 
010701 4 SOSEARCH 
01080C 01 . Z-ADD1 I 20 
01090¢ LOOP TAG 
O1100C O01 SEARCH LOKUPARY 1, I 56 
O1105C = 56 EXCPT 
01107C SETOF 56 
O1110C 01 1 ADD I I 
011420C 01 11 COMP I 54 
O1130C O01 54 GOTO LOOP 
OL114000UTPUT E 56 
011500 7 'INDEX=’ 
011600 I 9 
011700 48 VALUE=’ 
011800 ARY1,1 23 
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An example of the output file might appear as follows: 


0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 

123456789012345678901 2345678901 2345678901 2345678901 2345678901 2345678901 234567890 
INDEX=06  VALUE=40000 
INDEX=07  VALUE=30000 
INDEX=08  VALUE=20000 
INDEX=09  VALUE=10000 
INDEX=10  VALUE=00000 


The column numbers in this example are for reference and do not appear 
in the output. 


11.8 Moving Array Data 


You can use the MOVEA operation code to move the following array data: 


¢ Contiguous array elements to a field 
e A field or literal to contiguous array elements 


¢ Contiguous elements of one array to contiguous elements of another 
array : 


If the array is not indexed, data movement starts with the first element of 
an array or field. If the array is indexed, the move starts with the element 
you specify. Data movement stops when either of the following conditions 
is met: 


e The last array element is moved or filled. 


e The number of characters moved equals the length of the shorter field, 
as specified either in columns 33 through 42 (factor 2) or in columns 
43 through 48 (result field) of the Calculation specification. 


See Chapter 16 for more information on the MOVEA operation code. 
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The following example shows a preexecution-time array ARR20 being 
loaded from the file ARRFILE. A copy of ARR20 is moved into the 
execution-time array ARR15 using the MOVEA operation code. 





Oo be he Oe ei i a es ba ean te AG ob oe eT 
123456 78901234567890123456 7890123456 78901 2345678901 23456 789012345678901 234567890 





FARRFILE IT F 80 EDISK 

E ARRF ILE ARR20 5 5O 4 

E ARR15 50 4 

C MOVEAARR20 ARR15 
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11.9 Updating Arrays 


To change the contents of an element in a compile-time array, or to add 
new elements to a compile-time array, edit the source program containing 
the array data, and then recompile the program. | 


To change the contents of an element in a preexecution-time array, or to 
add new elements to such an array, edit the table input file that contains 
the array. 


You can make temporary changes in arrays during program execution by 
using the array name as a result field. You can make these temporary 
changes permanent by writing the array to an output file that you can use 
later as an input file. 


The following example describes the array COSTL, which consists of 
six-digit overpunched numeric data with two decimal places. This array is 
read from the file ARRAYIN. During program execution, changes can be 
made to this array. At the completion of the program, the array will be 
written to the output file ARRAYOUT. The format in which it is written 
is the same as that in which it was read, that is, eight entries in each 
record with each entry being a six-digit overpunched numeric data type 
with two decimal positions. The files ARRAYIN and ARRAYOUT must 
also be described on File Description specifications as an input table file 
(ARRAYIN) and an output table file (ARRAYOUT). 
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Format (PB) 


LEAS D = Decimal positions 
11 ----S = Sequence (AD) 
| 
ll lAlternating table or array 
To Table EntEnt Len!lIname Len 
file or perin of FIll of F 
name array RecTbl EntlDII Ent ID 
IS| | 11S 
Vt 


name | I 7 1 
| be. oe fe —f 4 





Roeerk 
E ARRAYIN ARRAYOUTCOSTL 


% % Ho-—R—— — K— RK 


8 100 62 


H-~KERE 
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11.10 Outputting Arrays 


You can output either an entire array or inaividiial array elements. To out- 
put entire arrays, you can make entries either in an Extension specification 
or in an Output specification. 


To write a compile-time or preexecution-time array using an Extension 
specification, you must make the following entry: 


Columns 19 through 26 (to file name)—specify the name of a se- 
quential output file. This file must have been previously defined in a 
File Description specification. The program automatically writes the 
compile-time or preexecution-time array you specified in the Extension 
specification to this output file after reaching the end of the program. 


To write a compile-time, preexecution-time, or execution-time array using 
an Output specification, you must make the following entries: 


Columns 32 through 37 (field name)—specify the name of the array 
you want to write. The array is written every time the program 
processes a record unless you specify indicators in columns 23 through 
31 of the Output specification. 


Columns 40 through 43 (end position)—specify the character position 
where the last entry of the array ends. 
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ECO 
E 
IFILEA 
I 


¢ Ot 
OF ILEB 


oooae 


In the following example, for each record read from FILEA, the execution- 
time array DISCNT is written out to the file FILEB using Output specifica- 


tions: 


STLIST 
AA Of 


PRICE 


D1 


0 | 4 2 3 ry Nl 5 6 l 7 
12345678901 23456789012345678901234567890123456 7890123456 789012345678901 23456789 





0 


PRICE 5 10 52 
DISCNT 10 52 


MULT PERCNT 


PERCNT3 


DISCNT 


4 22PERCNT 
DISCNT 


60 ‘COST WITH DISCOUNT OF ’ 
72 
74 7%! 


120’ $0. ’ 
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To output an individual array element, specify the array and the index of 
the desired element (in the form ARR,n, where n is either a constant or a 
field name) in columns 32 through 37 (field name). 


The following example outputs only the first and second elements of array 
DSCT: 





0 


E  COSTLIST 

E 

IFILEA AA O4 

J : 

C (OL PRICE 
OFILEB D 4 

0 

0 

0 

0 
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| 4 | 2 | 3 | 4 | 5 | 6 | 7 
123456 78901234567890123456 7890123456 78901234567890123456 7890123456 78901 234567890 


PRICE 5 140 
DSCT 10 


MULT PERCNT 


DSCT, 4 
DSCT,2 


4 22PERCNT 
DSCT 


20 “ITEM 1 COST: ’ 
32’ $0. ' 
50 “ITEM 2 COST: ’ 
62’ $0. 7” 
ZK-4447-85 


If you want to output numeric array elements, you can use edit codes or 
edit words to add commas or dollar signs, or to suppress leading zeros. 
Do not use edit codes or edit words to modify array data if you are going 
to use the data as input to subsequent programs. 


When you specify an edit code with an entire array (nonindexed), 
VAX RPG II automatically inserts two spaces between elements of the 
array in the output record. 
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Chapter 12 


Calling System Routines from VAX RPG Il 


This chapter describes the use of VAX RPG II operation codes to access 
VAX/VMS Run-Time Library (RTL) routines, system services, utilities 
(such as the VAX Forms Management System (VAX FMS) and the 

VAX Terminal Data Management System (TDMS)), and subprograms 
written in languages other than VAX RPG II’. You can access these 
routines by using the following VAX RPG II operation codes: 


CALL operation code—invokes the routine 
PLIST operation code—defines the parameter list, if used 


PARM, PARMD, and PARMV operation codes—determine the 
parameter-passing mechanism. 


GIVNG operation code—receives a function value or return status 


EXTRN operation code—defines a VAX RPG II name for an external 
symbol name 


See Chapter 16 for more information on these operation codes. 


Although calling VAX/VMS Run-Time Library routines, system services, 
utilities, and subprograms can provide many advantages, you should note 
the following: 


Do not call these routines if you can perform the task using 
VAX RPG II. | 


Do not mix VAX/VMS Run-Time Library and VAX RPG II output 
routines. . 


1 There are no VAX RPG II subprograms. VAX RPG II modules cannot be called from VAX RPG II or any 


other language. 
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e Ifa VAX/VMS Run-Time Library routine and a system service perform 
the same task, use the VAX/VMS Run-Time Library routine. 


System routines are subroutines and functions provided by the VAX/VMS 
operating system. Each system routine has an entry point (the routine or 

service name) and an argument list. Each system routine may also return 

a function value or condition value to the program that calls it. 


System routines perform common tasks, such as finding the square 
root of a number or allocating virtual memory. If you use system rou- 
tines, you will not have to rewrite code every time you want to perform 
a common task. Using system routines allows you to concentrate on 
application-specific tasks, not utility tasks. Some system routines even 
help independent parts of programs allocate resources cooperatively. 


A system routine can be called from any VAX/VMS language if that 
language supports the data structures required by the particular routine. 
The results of a system routine will be the same, no matter what language 
you use. 


The system routines that are most commonly called from user programs 
are VAX/VMS Run-Time Library routines and system services. These 
system routines are documented in the VAX/VMS Run-Time Library 
Routines Reference Manual and the VAX/VMS System Services Reference 
Manual. 


12.1 Run-Time Library Routines 


The VAX/VMS Run-Time Library routines are assigned facility names that 
represent specific types of common tasks. These facilities and the types of 
tasks they perform are shown in Table 12-1. 
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Table 12-1: VAX/VMS Run-Time Library Facilities 


Facility 
LIB$ 


MTH$ 
OTS$ 


SMG$ 


STR$ 


Tasks Performed 


General purpose procedures that obtain records from devices, manip- 
ulate strings, convert data types for I/O, allocate resources, obtain the 
system date or time, signal exceptions, establish condition handlers, 
enable detection of hardware exceptions, and process cross-reference 
data. 


Mathematics procedures that perform arithmetic, algebraic, and 
trigonometric calculations. © 


Language-independent support procedures that perform tasks such as 
data type conversions as part of a compiler’s generated code. 


Screen management procedures that assist you in designing, compos- 
ing, and keeping track of complex images on a video screen and that 
provide terminal-independent tasks. 


String manipulation procedures that perform tasks such as searching 
for substrings, concatenating strings, and prefixing and appending 
strings. 


12.2 System Services Routines 


The VAX/VMS system services are routines that perform various tasks 
such as controlling processes, communicating among processes, and 
coordinating I/O. 


Unlike VAX/VMS Run-Time Library routines, which are grouped by 
facility name, all system services share the same facility prefix (SYS$). 
However, these services are logically divided into groups of services that 
perform similar tasks. Table 12-2 describes these groups. 


Table 12—2: Groups of VAX/VMS System Services 


Group Tasks Performed 

AST Allows processes to control the handling of 
ASTs 

Change Mode Changes the access mode of particular routines 

Condition Handling Designates condition handlers for special 
purposes 
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Table 12-2 (Cont.): 
Group | 


Event Flag 
Information 


Input/Output 


Lock Management 


Logical Names 
Memory Management 


Process Control 


Security 


Timer and Time 
Conversion 


Groups of VAX/VMS System Services 


Tasks Performed 
Clears, sets, reads, and waits for event flags, 
and associates with event flag clusters 


Returns information about the system, queues, 
jobs, processes, locks, and devices 


Performs I/O directly, without using VAX RMS 


Enables processes to coordinate access to 
shareable system resources _~ 


Provides methods of accessing and maintaining 
pairs of character string logical names and 
equivalence names 


Increases or decreases available virtual memory, 
controls paging and swapping, and creates and 
accesses shareable files of code or data 


Creates, deletes, and controls execution of 
processes 


Enhances the security of VAX/VMS systems 


Schedules events; obtains and formats binary 
time values 


12.3 Procedure for Calling System Routines 


Seven steps are required to call any system routine: 


Ie Sh Oe. Ve Le 


Locate the result 
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Declare the system routine 
Declare the arguments 


Call the routine or service 


Determine the type of call (function or procedure) 
Include symbol definitions (if applicable) 


Check the condition value (if applicable) 


In the following sections, you can follow these steps in writing a program 
to call the VAX/VMS Run-time Library routine LIB6STAT_TIMER. This 
system routine returns one of five statistics: (1) elapsed time, (2) CPU 
time, (3) buffered I/O count, (4) direct I/O count, or (5) page fault count. 


12.3.1 Declare the System Routine 


Declare a system routine in your program as you declare any other 
external routine. The declaration statement will vary depending on 
whether the system routine is being called as a function or procedure. 


The routine declaration statement for calling LIB$STAT_TIMER as a 


function should appear as follows: 


Field length 


Control level ° | Decimal positions 
| 1 Half adjust (H) 
| Indicators Operation i oti 

Pt | 1 {Resulting 

| Factor si Factor Result! IJlindicators 

| | | 2 field | Il+- 0 


Cl NxxNxxNxx | | | Jty < = +- Comments --+ 






i] 


1234567890123456 7890123456 7890123456 7890123456 7890123456 789012345678901234567890 


1 | 2 3 | 4 | a) 5) | 7 | 


% % * * H--HEK HOKE 
STATIM EXTRN’LIBSSTAT_TIMER’ 
CALL STATIM 


PARM CODE 90 RL 
PARM VALUE 90 WL 
GIVNG RETVAL 
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The routine declaration statement for calling LIB$STAT_TIMER as a 
procedure should appear as follows: 


Field length 
Control level | Decimal positions 


| {Half adjust ¢H) 
| Indicators Operation oe 
I | . | | | iResulting 
| Factor | Factor Result! Jlindicators 
I | | | 2 . field | Il+- 0 
Cl Bibbs! oe | | | 1 i> < = +- Comments --+ 





2 R) 4 I a) | 3) | 7 | 
Sa RE ELE EL LE Ce CE ee ee ee 
Re % , % H--HRE HHH 
¢C STATIN EXTRN’ LIBSSTAT_TINER’ 
C CALL STATIM 
: PARM CODE 90 RL 


PARM VALUE 90 WL 
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12.3.2 Determine the Type of Call (Function or Procedure) 


Before you can call a system routine or service, you must determine 
whether the call should be a function call or a procedure call by referring 
to the Returns section of the system routine documentation. 


A system routine must be called as a function if it returns a condi- 
tion value or a function value. For example, the Returns section of the 
LIB$STAT_TIMER system routine documentation contains the following 


description: 
RETURNS 
VMS Usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Because the LIB$STAT_TIMER system routine returns a condition value, 
you must call it as a function. 


NOTE 


To call a system routine as a function in VAX RPG II, you must 
use the GIVNG operation code. 
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You can call many system routines as procedures, if you choose not to 
refer to the condition code. This is highly discouraged because it can lead 
to many undiscovered errors. (Checking condition values is described in 
Section 12.3.6.) DIGITAL recommends that you call a system routine as a 
procedure only if it does not return a condition value or a function value. 
In this case, the Returns section of the system routine documentation 
contains the following description: 


RETURNS 
None 


12.3.3 Declare the Arguments 


Most system routines have one or more arguments that you can use to 
pass information to the system routine and to obtain information from the 
system routine. Arguments can be required or optional. 


For example, consider the arguments for the VAX/VMS Run-Time Library 
routine LIB$6STAT_TIMER. This routine has three arguments; two are 
required and one is optional. You can determine which arguments are 
required by looking at the Format section of the system routine documen- 
tation. In the case of LIB6STAT_TIMER, the format is as follows: 


LIB$STAT_TIMER code ,value [,handle-adr] 


The handle-adr argument appears in brackets ([]), indicating that it is 
an optional argument. Optional arguments to a system routine appear in 
brackets in that routine’s Format section. For this example, you want to 
declare only the two required arguments, code and value. 


To declare an argument for a system routine, first check that argument’s 
description in the system routine documentation. The argument descrip- 
tion for the code argument is as follows: 


code 


VMS Usage: function_code 

type: longword integer (signed) 
access: read only 

mechanism: by reference 


The code argument contains the address of a signed longword, and that is 
the statistic returned by LIB6STAT_TIMER. The signed longword must be 
an integer from one to five. 
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The VMS Usage function—code indicates that the data type returned by 
the routine is dependent on other factors. Table 12-3 lists the — 

VAX RPG II equivalent for each of the VAX/VMS Usages. You can declare 
the argument using the code provided in Table 12-3. 


The following example shows that the parameter contained in the field 
CODE of the code argument is passed by reference: 


Field length 
Control level | Decimal positions 
} IHalf adjust (H) 
Hl 















| 
| Indicators Operation | 
1 | | | !lResulting 
1 | Factor | Factor Result! tlindicators 
1 | | | 2 field | [l+- 0 
Cl NxxNxxNxx | | ! | —t Lis < = +- Comments --+ 
0 | 1 | 2 | 3 | 4 | 5 | Ls) | ‘i | 
eat SEA EA be LCE EE EEE EE TE 


REO ae ee 
C PARM CODE 90 RL 
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For more information on parameter-passing mechanisms, see 
Section 12.3.3.1. 


The procedure used in declaring the code argument is also used in declar- 
ing the value argument. First, check the argument description for the 
value argument: 


value 


VMS Usage: varying_arg 
type: unspecified 
access: write only 

mechanism: by reference 


The value argument contains the address of a longword or quadword, 
and that is the statistic returned by LIB${STAT_TIMER. All statistics are 
longword integers except elapsed time, which is a quadword. 


The VMS Usage varying_arg indicates that the data type returned by the 
routine is dependent on other factors. In this case, the data type returned 
is dependent on the statistic you want to return. For this example, the 
statistic that you want to return is code 5, page fault count. This statistic 
is returned in a signed longword integer. Therefore, you need to check 
Table 12-3 to find the VAX RPG II statements that are used to declare a 
longword_signed data structure. 
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The declaration statements for all VAX/VMS routines and system ser- 
vices arguments can be found by looking up the VAX/VMS Usage in 


Table 12-3. 


Table 12-3: VAX/VMS Data Structures 


VAX/VMS Data Structure 


access__bit_names 


access._.mode 


address 
address_range 
arg_list 
ast_procedure 
boolean 


byte_signed 


byte_unsigned 
channel 
char_string 
complex_number 


cond_value 


context 

date_time 
device_name 
ef_cluster_name 
ef_number 
exit_handler—_block 


VAX RPG II Implementation 
NA 


Declare as text string of one byte. When 
using this data structure, you must 
interpret the ASCII contents of the string 
to determine the access_mode. 


L 
Q! 
NA 
LU} 
NA 


Declare as text string of one byte. When 
using this data structure, you must 
interpret the ASCII contents of the string. 


Same as for byte_signed.! 
w! 

TEXT STRING 

DATA STRUCTURE 


condvalue GIVNG OPCODE 
Columns 43 through 58 


L} 

Q! 

TEXT STRING 
TEXT STRING 

L} 

DATA STRUCTURE 


VAX RPG Il does not typically support unsigned data structures. However, unsigned information 
may be passed using the signed equivalent, if the contents do not exceed the range of the signed 


data type. 
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Table 12-3 (Cont.): 
VAX/VMS Data Structure 


fab 


file_protection 


floating—_point 


function_code 
io_status_block 
item —list_2 
item —list_3 
item—quota_list 
lock—id 
 lock_status—_block 
lock_value_block 
logical_name 
longword_signed 
longword_unsigned 
mask_byte 
mask_longword 
mask_quadword 
mask__word 
null_arg 
octaword_signed 
octaword_unsigned 
page—protection 
procedure 


process_id 


VAX/VMS Data Structures 


VAX RPG II Implementation 


Generated implicitly by the compiler on 
your behalf. It is not possible for a user 
to access the fab data structure from a 
VAX RPG II program. 


w! 

F or D 

Column 55 

F 

Q 

DATA STRUCTURE 
DATA STRUCTURE 
NA 

L} 

DATA STRUCTURE 
DATA STRUCTURE 
TEXT STRING 

L 

} 

NA 

L} 

Q! 

w! 

NA 

DATA STRUCTURE 
DATA STRUCTURE 
u} 

u} 

L} 





1 vax RPG II does not typically support unsigned data structures. However, unsigned information 
may be passed using the signed equivalent, if the contents do not exceed the range of the signed 


data type. 
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Table 12-3 (Cont.): VAX/VMS Data Structures 


VAX/VMS Data Structure 


process_name 
quadword_signed 
quadword_unsigned 
rights_holder 

rights_id 

rab 

section —id 
section_name 

system —access_id 
time_name 

uic 

user_arg 

varying_arg 
vector_byte_signed 
vector_byte_unsigned 
vector_longword_signed 


vector_longword_unsigned 
vector_quadword_signed 
vector_quadword_unsigned 


vector_word_signed 


vector_word_unsigned 
word_signed 


word_unsigned 


VAX RPG II Implementation 
TEXT STRING 


TEXT STRING 
Q! 

TEXT STRING 

L} 

L} 

Dependent upon application. 
ARRAY OF CHARACTER STRING 
ARRAY OF CHARACTER STRING! 


ARRAY OF LONGWORD INTEGER 
(SIGNED) L 


ARRAY OF LONGWORD INTEGER L!. 
NA 
NA 


ARRAY OF WORD INTEGER (SIGNED) 
W 


ARRAY OF WORD INTEGER W! 
Ww 
Ww! 


1VAX RPG II does not typically support unsigned data structures. However, unsigned information 
may be passed using the signed equivalent, if the contents do not exceed the range of the signed 


data type. 
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12.3.3.1 Parameter-Passing Mechanisms 
This section describes conventions for passing arguments in VAX RPG II 
programs. 
A calling program can pass a parameter in one of three ways: 


e By value—the PARMV operation code passes a parameter by value. 


e By reference—the PARM operation code passes a parameter by 
reference. 


e By descriptor—the PARMD operation code passes a parameter by 
descriptor. 


When the PARMV operation code passes a parameter by value, the 
parameter list contains the actual, uninterpreted 32-bit value of the 
parameter. 


In the following example, the constant 0 is passed by value: 
Field length 


Control level | Decimal positions 
IHalf adjust (H) 
VI 





| 
| Indicators Operation | 
1 | | | tiResulting — 
1 | Factor | Factor Result! llindicators 
1 | | | 2 field | il+t - 0 
Cl NxXxNxxNxx | | I | 1 I> < = +- Comments --+ 
| | 2 | 3 | 4 | a) | 6 | 7 | 
12345678901234567090123456789012345678901234567890125456789012346 7890123456780 
He % ee i 
C PARHY. 0 


ZK-4632-85 


When the PARM operation code passes a parameter by reference, the 
parameter list contains the address of the location that contains the value 
of the parameter. Most languages pass scalar data by reference. 


Character data is always passed as a fixed-length string. Numeric data, 
by default, is passed as a packed decimal string. When passing a param- 
eter by reference, you may specify an access type and a data type for 
numeric data in columns 54 through 57 of the Calculation specification. 
Sections 12.3.3.2 and 12.3.3.3 describe access and data types in detail. 


In the following example, the parameter contained in the field TIMLEN is 
passed by reference. 
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Field length 
Control level | Decimal positions 
| 1 IHalf adjust (H) 
ll 


| Indicators Operation | 

| | IlResulting 
| Factor | Factor Result! tlindicators 
1 | 1 I 2 field | Il+- 0 


- Cl NxxNxxNxx | sel | | | JIl> < = +- Comments --+ 








RH x % x H--HRK HH 
¢ PARM TIMLEN 90 WL 
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When the PARMD operation code passes a parameter by descriptor, the 
parameter list entry contains the address of a descriptor for the parameter. 


In the following example, the field TIMBUF containing the parameter 
(fixed-length string) is passed by descriptor: 


Field length 
Control level | Decimal positions 
| IHalf adjust (H) 


| 
| Indicators Operation 1 od 
1 | | | [lResulting 
I | Factor | Factor Result! !lindicators 
1 | | 


| é field | Il+- 0 
| 


Cl_NxxXNxxNxx | l1> < = +- Comments --+ 









0 rT 3 | 4 { 5 | 6 | 7 | 
ER LELVACU CRE VASA GCYACURERE GCYECUSERECLYELCUSERY GUYELUSERE GCYALUSERE Wai sWesc 10) 
HE. # ¥ ¥ ¥ ¥ R--HEE HH 
C PARMD TIMBUF 23 
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In passing the arguments to the procedure, you must declare the passing 
mechanism. When passing parameters by descriptor (using me PARMD 
operation code), VAX RPG II uses: 


e An array descriptor for entire arrays 


¢ A scalar decimal descriptor for numeric data with positions to the right 
of the decimal point 


e A scalar descriptor for all other data types 
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VAX RPG II passes parameters in a scalar format, unless the parameter is 
an entire array. 


The passing mechanism required for a system routine argument is in- 
dicated in the argument description. This is shown in the following 
description of the one-char-str argument to LIB$CHAR: 


one-char-str 


VMS Usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


In this case, the required passing mechanism is by descriptor. The 
passing mechanisms allowed in system routines are those listed in the 
VAX Procedure Calling and Condition Handling Standard section of the 
Introduction to VAX/VMS System Routines. 


NOTE 


Any passing mechanisms not described in this section are 
unsupported in VAX RPG II. If a system routine requires a 
passing mechanism not described in this section, it is not 

possible to call that routine directly from VAX RPG II. 


You are required to specify the passing mechanism, as shown in the 
following example, where the PARM operation codes indicate that both 
CODE and VALUE are being passed by reference: 


. Field length 
Control level | Decimal positions 
| IHalf adjust (H) 


















| 
| Indicators Operation ) 4 
1 | | 1 tiResulting 
1 | Factor | Factor Result! llindicators | 
1 4 i 2 field | Il+ - 90 
Cl NxxNxXNXXE 1. | | 1 Jt> < = +- Comments --+ 
) | 4 | 2 | 3 4 | 5 6 | 7 | 
123456 7890123456 7890123456 78901234567890123456 7890123456 7890123456 78901 234567890 
HH * % % % % H--HKRH KH HK 
C STATIM EXTRN’LIB$STAT_TIMER’ 
C CALL STATIM 
C PARM CODE 90 RL 
C PARM VALUE 90 WL 
C GIVNG RETSTA 


ZK-4643-85 
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12.3.3.2 Parameter Access Types (Column 54) 


The parameter access type indicates the actions that the VAX/VMS Run- 
Time Library routine is permitted to perform on the parameter. Access 
types that you can use in VAX RPG II are as follows: 


¢ Read-only (R)—the parameter can only be read. 
e Write-only (W)—the parameter can only be written. 
° Modify (M)—the parameter can be modified (read and written). 


You can specify the parameter access type and data type with the PARM 
operation code. If you specify a parameter access type, you must also 
specify its data type. 


In the following example, the TIMLEN field is a longword integer (column 
55) with write-only access (column 54): 


Field length 
Control level | Decimal positions 
| IHalf adjust (H) 
Hl 





| 
| Indicators Operation | 
1 | | | [lResulting 
| Factor | Factor Result! Ilindicators 
1 | i | 2 field | Il+- 0 
Cl NxxXNxxNxx | | | | { J1l> < = +- Comments --+ 
) | 
RE * ¥ % % R--KHEK HH ¥ 
C PARM TIMLEN 90 WL 
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12.3.3.3 Parameter Data Types (Columns 55 through 57) 


If you specify a parameter access type, you must also specify its data type. 
The following parameter data types can be passed from a VAX RPG II 
program to a VAX/VMS Run-Time Library routine: 


e Word integer (W)—signed 

e Longword integer (L)—signed 
e Quadword integer (Q)—signed 
e F_floating single-precision (F) 

e D_floating double precision (D) 
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¢ Numeric string, right overpunched sign (NRO) 
¢ Packed decimal string—default data type for numeric data 
e Character string—default data type for character data 


Define the parameter data type in columns 55 through 57 of the 
Calculation specification. You can specify a data type only for numeric 
fields passed by reference. 


In the following example, the data type of the numeric field TIMLEN is a 
right overpunched sign (NRO): 


Field length 
| Decimal positions 


Control level 
| IHalf adjust (H) 


: 
| Indicators Operation 1 ott. 
1 | | | lfResulting 
| Factor | Factor Result! tlindicators 
1 | 1 | 2 field | Il+- 0 
Cl NxxNxxNXXxI | | | 1 Itty < = +- Comments --+ 
| 1 | 


hase hr ome © Mee ih Ade 3 fo 4 





ASE LCE ER LEENA EER eS EE SEY 
Hx % % ¥ H-~HKE HK 
C PARM TIMLEN MNRO 
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12.3.4 Include Symbol Definitions 


Many system routines require values that are defined in separate symbol 
definition files. For example, when you call any VAX/VMS Run-Time 


Library routine in the VAX Screen Management (VAX SMG$) facility, you 
must include the file SMGDEF. 


VAX/VMS Run-Time Library routines require you to include symbol 
definitions when you call a VAX Screen Management (VAX SMG$) 
routine, or a routine that is a jacket to a system service. (A jacket routine 
provides a simpler, more easily used interface to a system service.) 


All system services routines require you to include the file System Services 
Definition File (SSDEF) to check status. Many system services require 
other symbol definitions as well. To determine whether you need to 
include other symbol definitions for the system service you wish to 

call, refer to the documentation for that service. For example, if the 
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documentation states that values are defined in the foobar macro, you 
must include those symbol definitions in your program. 


In VAX RPG II, a definition macro is included as follows: 


$ CREATE SMGDEF.MAR 
.TITLE SMGDEF - Define SMG$ constants 
$SMGDEF GLOBAL 
. END 

$ MACRO SMGDEF 

$ LINK RPGPROG, SMGDEF 


The LIB6STAT_TIMER system routine does not use any included defini- 
tion files, so this step is not applicable for this example. 


12.3.5 Call the Routine or Service 


The call to a VAX/VMS Run-Time Library routine or system service is set 
up as an external call in VAX RPG II. The syntax of the CALL statement 
will depend on whether the call is a function call or a procedure call. 


12.3.5.1 Calling a System Routine as a Function Call 


Call a system routine as a function call according to the Format section in 
the routine or service description. For example, the format for 
LIB$STAT_TIMER is as follows: 


LIB$STAT_TIMER code ,value [,handle-adr] 


In a format statement, an optional argument can appear in one of two 
ways: 

e [optional-argument] 

¢ _foptional-argument] 

In general, VAX/VMS Run-Time Library routines use the format 
[,optional-argument]. If the comma appears inside the brackets 
(Loptional-argument]), you can omit the optional argument if it is the last 


argument in the list. For example, look at the optional arguments of an 
imaginary routine, LIB$EXAMPLE_ROUTINE: 


LIB$EXAMPLE_ROUTINE argi [,arg2] [,arg3] [,arg4] 
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You can omit all of the optional arguments without using a placeholder, 


as shown in the following example: 


Control level 


| 
| Indicators Operation | 
| | 
1 | Factor | Factor Result] 
| | . 4 2 field | 


Cl NxxNxxNxx | | | | | 


Field length 
| 


Decimal positions 
lHalf adjust (H) 
Hl 


| |Resulting 

| indicators 

1l+ - 0 

[I> < = +- Comments --+ 





4 | | 5 | 6 I a | 
125456 78901234567890125456 78901254567890123456 7890123456 7890123456 78901234567890 
HE % *% % x % R--ERK HR 
¢ LIBEXA EXTRN’LIBSEXAMPLE_ROUTINE’ 
C CALL LIBEXA 
¢C PARM ARG 
C GIVNG RETSTA 


ZK-4640-85 


However, if you omit an optional argument in the middle of the argument 
list, you must insert a placeholder, as shown in the following example: 


Field length 


Control level | 
| 


| Indicators Operation | 
1 | I | 
1 | Factor | Factor Result! 
1 | i. | 2 field | 


Cl NxxNxxNxx | | | | | 


Decimal positions 

IHalf adjust ¢H) 

a ; 

| lResulting 

| lindicators 

li+ - 0 

[I> < = +- Comments --+ 





R) | 4 3) | ) | 7 | 

123456 7890123456 7890123456 78901234567890123456 7890123456 7890123456 78901234567890 

RE *€ ¥ % % * H--KRE ¥ H ¥ 

C LIBEXA EXTRN’LIB$SEXAMPLE_ROUTINE’ 

C CALL LIBEXA 

C PARM ARG1 

C PARMV 0 

C PARM ARGS 

C GIVNG RETSTA 
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Calling the system routine LIB,EXAMPLE_ROUTINE as a function call 
using all optional arguments would appear as in the following example: 


Field length 
co level | Decimal positions 


IHalf adjust (H) 





| 
| Indicators Operation 1 tl 
1 | I | {Resulting 
1] Factor | Factor Result! [lindicators 
Pt 1 | 2 field | [tl+-0 
Cl NxxNxxNxx | cette A | | I> < = +- Comments --+ 
| 2 | 4 | 5 | 6 | v4 | 
Da aac ee ea en ee OL ae eae ete 3072) 
HH % % % % H--KHEK HH * 
¢C LTREXA EXTRN’LIBSEXAMPLE_ROUTINE’ 
¢C CALL LIBEXA 
C PARM ARG! 
C PARM ARG2 
C PARM ARGS 
C GIVNG RETSTA 
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In general, VAX/VMS system services use the format ,[optional-argument]. 
If the comma appears outside the brackets (,[optional-argument]), you must 
pass a zero by value. In the following example, the constant 0 is passed 
by value: 


Field length 
Control level | Decimal positions 
| IHalf adjust (H) 
I! 





| 
| Indicators Operation | 
1 | | | [tResulting 
1 | Factor. | Factor Result! llindicators 
1 | 1 | 2 field | Il+- 0 
Cl NxxNxxNxx | | A I . | Ws < = +- Comments --+ 
1 | 3 | 4 1 l 6 | 7 | 
1234567890123456 7890123456 7890123456 7890123456 7890123456 7890123456 78901234567890 
¥% % % % % x H--HEX HX 
Cc PARMV 0 


ZK-4636-85 
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12.3.5.2 Calling a System Routine as a Procedure Call 


If the routine or service you are calling does not return a function value 
or condition value, you may call the system routine as a procedure. The 
same rules apply to optional arguments, and you should still follow the 
calling sequence presented in the Format section of the routine or service 
description. 


One system routine that does not return a condition value or func- 
tion value is the VAX/VMS Run-Time Library routine LIB$SIGNAL. 
LIB$SIGNAL should always be called as a procedure, as shown in the 
following example: 


Field length 
Control level | Decimal positions 
IHalf adjust (H) 
| 


| 
| Indicators Operation 1 | 
1 | | | [Resulting 
1 | Factor | Factor Result! Illindicators 
1 | 1 | 2 field | Jit - 0 
Cl NxxNxxNXx I I. | | 1 Ils < = +- Comments --+ 
) | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 










TASES AE ERE as SEAR ea TR EE A re 


HE * x * H--KEK HOR H 
¢ SIGNAL EXTRN’LIB$SIGNAL’ 
¢C CALL SIGNAL 


¢ PARMY CODE 90 
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12.3.6 Check the Condition Value 


After you call the system routine and control is returned to your program, 
you should check the condition value returned (if there is one). In general, 
all system routines return a condition value with the following exceptions: 
¢ The system routine returns a function value. 
¢ The system routine has no condition values. 


° The system routine has no condition values returned, but rather, has 
condition values signaled. (Success conditions are not signaled.) 


e The call to the routine was made as a procedure call. 


These exceptions are described in the Returns, Condition Values Returned, 
or Condition Values Signaled section of the system routine documentation. 
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If there is a condition value, you must check this value to make sure 
that it indicates success. All success condition values are described in the 
Condition Values Returned section of the system routine documentation. 
Success condition values always appear first in this list. 


Many system routines return the condition value SS$_NORMAL as a 
success value. If this is the only possible success condition, you can test 
for its presence, as shown in the PHONE example: 


Field length 
Control level | Decimal positions 
| IHalf adjust (H) 
I 


| 
| Indicators Operation | 
1 | | | (tlResulting 
ibs = Factor | Factor Result! Jlindicators 
1-t co | | 2 field | Il+ = 0 
Cl NxxNxxXNxxE 00s | | 1 i> < = +- Comments --+ 

















) | 4 | Fe | 3 | 4 5 | 7 
ECAC Ee AG REC IE RA REE Dee CELE 

HH % * * H--KEK HR K 

¢ SSNORM EXTRN’SS$_NORMAL ’ 

C STATIM EXTRN’LIB$STAT_TIMER’ 

¢ CALL STATIM 

¢ PARM CODE 90 RL 

C PARM VALUE 90 WL 

¢ GIVNG RETSTA 

¢ SSNORM COMP RETSTA O41 

¢ STOP EXTRN’LIB$STOP’ . 

C NO1 CALL STOP ' 

¢C PARMV RETSTA 90 RL 


2K-4645-85 
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C 
0 
123456 







It is also possible to check for any success code because all success codes 
have an odd value (not evenly divisible by 2). The following example 
program segment will continue execution if any success code is returned. 
The call to STATIM is conditioned by an indicator which will be set off if 
any success code is returned. 


Field length 
Control level 1 Decimal positions 
| IHalf adjust (H) 
11 


| 
| Indicators Operation 1 | 
1 | . | | JlResulting 
I | Factor | Factor Result! IJlindicators 
1 | | | 2 field | Il+- 0 


| tl>-< = +- Comments --+ 





| NxxXNxXxNX>x | ae) aes ee 
| 1 





| 2 | 3 | 4 | 5 3) | 7 | 
7890123456 7890123456 78901234567890123456 7890123456 7890123456 7890123456 7890 
* ¥. ¥ - x H-—-HEK HX % , 
STATIM EXTRN'LIBSSTAT_TIMER’ 
CALL STATIM 01 
PARM CODE 90 RL 
PARM VALUE 90 WL 
GIVNG RETSTA 
STOP EXTRN’LIB$STOP’ 
01 CALL STOP © 
PARMYV RETSTA 90 RL 


ZK-4646-85 
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When several success condition values are possible, you can continue exe- 
cution on specific success codes. For example, the system service $SETEF 
returns one of two success values, SS$¢_WASSET or SS$_WASCLR. If you 
want to continue when the success code SS$_WASSET is returned, you 
can check for this condition value as follows: 


Field length 
Control level | Decimal positions 
| IHalf adjust (H) 


ill 
| Indicators Operation rou 
1 | | | [lResulting 
1 | Factor | Factor Result! tlindicators 
1 | | | 2 field | [lt - 0 
Cl NxxXNXxXXNdXx | | { | | Its < = +- Comments --+ 





| 2 | 3 | 4 | 4) | 6 | 7 | 

RAO AUTOR TEES TO EI TEE Ee YE 

HE x % * H--HEH HH H 

C SETEF EXTRN’ SYSSSETEF’ 

CALL SETEF 

C PARM EFN RL 

¢ GIVNG RETSTA 

Co WASSET EXTRN’SS$_WASSET’ 

¢C WASSET COMP RETSTA 01 
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If indicator 01 is on, then SS$_WASSET was returned by the call. 


If the condition value returned is not a success condition, then the routine 
did not complete normally and the information it was to return may be 
missing, incomplete, or incorrect. 
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If the condition value returned was not a success code, you can check for 
a particular error condition, as shown in the following example: 


0 | 1 2 R) | 4 | 4) | 3) | 7 
12345678901234567890123456 7890123456 7890123456 7890123456789012345678901234567890 





™ 
* 
mm 


x *  # # H--HRE HOR X 
MOVE ‘Input: ’ PRMSTR 7 


C 

¢ RMSEOF EXTRN'RMS$_E0F’ 

C GETINP EXTRN’LIB$GET_INPUT’ 

C CALL GETINP 02 
C PARMD INPSTR255 

C PARMD PRMSTR 

C PARM INPLEN WW 
C . GIVNG RETVAL 

C 02 ‘Error’ DSPLYTTY 

C «(02 RMSEOF COMP RETVAL 03 
C «(03 ’ EOF’ DSPLYTTY 
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12.3.7 Locate the Result 


After you have declared the arguments, called the routine, and checked 
the condition value, you are ready to use the result. To find out where 
the result is returned, look at the description of the system routine you are 
calling. 


12.3.7.1 Function Results 


If the system routine is called as a function, the result is written into the 
variable in factor 2 of the GIVNG operation code. 


For example, in the call to MTH$ACOS in the following example, the 
_ result is written into the variable RESULT: 


Panag Sy a ae ee nie as ae eT 





1234567890123456 7890123456 7890123456 7890123456 7890123456 7890123456 78901234567890 
HR % x % x % H--KHRE KR RE 
C ACOS EXTRN’MTH$ACOS’ 
¢ CALL ACOS 
C PARM cos RF 
C GIVNG RESULT 


Z2K-4649-85 
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This result is described in the Returns section of the system routine 
description. 


12.3.7.2 Procedure Results 


If the system routine is called as a procedure, the result is written into 
one or more of the arguments. To determine which argument holds the 
result, examine the access entry in each of the argument descriptions. If 
the access entry in an argument description is “write-only” or “modify”, 
that argument contains output information written by the procedure. 


For example, LIB6CURRENCY returns the default system currency symbol 
($). The following argument description shows that the currency string is 
returned in the currency—str argument: 


currency_str 


VMS Usage: char_string | 
type: character string 
access: write only 
mechanism: by acc 


In all system routines, the output information returned by the routine or 
service has an access of “write-only” or “modify”. 


12.4 Examples of Calling VAX/VMS Run-Time Library Routines 


The following examples demonstrate calls to VAX/VMS Run-Time Library 
routines from VAX RPG II programs. 


You cannot call all VAX/VMS Run-Time Library routines because 

VAX RPG II cannot supply some types of parameters, such as addresses. 
See the VAX/VMS Run-Time Library Routines Reference Manual for infor- 
mation on all VAX/VMS Run-Time Library routines and the parameters 
they require. 
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The following example shows a call to the STR$UPCASE routine to 
change the lowercase string to uppercase letters. This routine requires two 
parameters: (1) the source string, and (2) the destination string. Both the 
source string HEAD and the destination string RESULT must be passed by 
descriptor, so the PARMD operation code is used. 


Because the name of this VAX/VMS Run-Time Library routine is longer 
than eight characters, the EXTRN operation code is used to refer to 
STR$UPCASE as UPCASE. 


Field length 
Control level | Decimal positions 
| IHalf adjust (H) 
VI 





| 
| Indicators Operation | 
1 | | | tlResulting 
| Factor | Factor Resultl llindicators 
lt i | 2 field | Ilt - 0 
Ci NxxNxxNxx | | | | | tl> < = +- Comments --+ 
| 2 | 3 | 4 | 5 } 6 | 7 | 
1234567890123456789012345678901234567890123456 7890123456 7890123456 78901234567890 
¥* % % % % % H--KHK HOH OK 
C MOVE ‘rep head’HEAD 8 
¢ UPCASE EXTRN’ STRS$UPCASE’ 
C CALL UPCASE 
C PARMD RESULT 8 
C PARMD HEAD 
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The following example calls the LIB$SET_SYMBOL routine to redefine 
the Command Language Interpreter (CLI) symbol MY_PARAMETER to 
be the string OFF. This routine requires two parameters to be passed by 
descriptor: (1) the symbol to be defined, and (2) the value to be given 
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to the symbol. Line 220 moves the string OFF (the value to be given to 
the symbol) to the field SETVAL. Line 230 assigns a five-character name, 
STSYM, to this routine name. Lines 240 and 250 assign the 12-character 
string MY_PARAMETER to the field SYMBL, the symbol to be defined. 
Line 260 invokes this routine. Lines 270 and 280 pass the two parameters 
to the routine. 


Field length 





Control level | Decimal positions 
I | tHalf adjust (H) 
| Indicators Operation 1 4 
1 | . | 1 JtResulting 
1 | Factor | Factor Result! Ilindicators 
1] | | 2 field | Il+ - 0 . 
Cl NxxNxxNxx | | | 1 | Ils < = +- Comments --+ 
H) 2 3 | rt 5 | 6 | 7 
el AEE EE TM ET EE LTA YER CR oT EEE 
x % % # H--HEE HHH 
2200 NOVE "OFF SETVAL 3 
230C ~ STSYM EXTRN’LIB$SET_SYMBOL ’ 
240¢ MOVE ‘METER’ SYMBL 12 
250C MOVEL’MY_PARA’ SYMBL 
2600 CALL STSYM 
270€ PARMD SYMBL 
2800 PARMD SETVAL 
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The following example calls the LIB$GET_INPUT routine to ask the user 
for input from the terminal screen. This procedure requires three param- 
eters: (1) the input text INPSTR (passed by descriptor) from the screen, 
(2) the prompt string PRMSTR (passed by descriptor) that is displayed 
before accepting input, and (3) the number of characters INPLEN (passed 
by reference) that are written to the input text. Also, this example des- 
ignates the field RETVAL to accept the return status (RMS$_EOF is the 
VAX/VMS Run-Time Library symbolic constant representing one possible 
return status) of the operation. The program uses the EXTRN operation 
code to retrieve the value of the symbolic constant representing a return 
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status. If the operation is unsuccessful, indicator 02 is set on and the string 
Error is displayed on the screen. If the operation is unsuccessful because 
the file is at the end-of-file, the string EOF is also displayed. 


Field length 
Control level . | Decimal positions 
IHalf adjust (H) 


1 
| Indicators Operation 1 dl 
1 | | | JlResulting 
| Factor I Factor Result! Ilindicators 
1 | | | 2 field | Jit - 90 


Cl NxxNxxNxx | | | I> < = +- Comments --+. 








HE * % % 


C MOVE. "Input: * PRUSTR 4 

C RMSEOF EXTRN’RMS$_EOF’ 

C GETINP EXTRN’LIB$GET_INPUT’ 

C CALL GETINP 02 
C PARMD INPSTR255 

C PARMD PRMSTR 

C PARM INPLEN WW 
C GIVNG RETVAL 

Cc 02 ‘Error’  DSPLYTTY 

C 02 RMSEOF COMP RETVAL 03 
C 8603 ’ EOF’ DSPLYTTY 


H--KHRK HK HF 
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The information provided in this chapter is general to all VAX/VMS Run- 
Time Library routines and system services. For specific information on 
these routines, refer to the VAX/VMS Run-Time Library Routines Reference 
Manual and the VAX/VMS System Services Reference Manual. 


12.5 Examples of Calling VAX/VMS System Services 


Most system services are used primarily by the VAX/VMS operating 
system on behalf of users. However, many system services are useful for 
application programming. 


The use of some system services is restricted to protect system perfor- 
mance and the integrity of user processes. The privileges and quotas 
assigned in the User Authorization File (UAF) determine whether you can 
use a restricted system service. These privileges and quotas apply to every 
image that your process executes. 
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The following example calls the SYS$ASCTIM system service to obtain 
the time. The time is converted from 64-bit system time format to an 
ASCII string. This service requires three parameters: (1) the length of the 
returned output string TIMLEN (passed by reference), (2) the character 
string TIMBUF, to receive the converted time (passed by descriptor), and 
(3) the conversion value 0 (passed by value). A conversion value of 1 
causes only the hour, minute, second, and hundredth of a second fields 
to be returned. A value of 0 causes the full date and time to be returned. 
Note that the length of the returned output string must be long enough 
to accommodate the data to be returned. Because the TIMLEN parameter 
must be a longword, the access type (write-only) and data type (longword 
integer) are specified in columns 54 and 55. 


If the operation is successful, the date and time (TIMBUF) are displayed 
on the screen. If the operation is unsuccessful, indicator 02 is set on. 


Field length 
Control level | Decimal positions 
| IHalf adjust (H) 
I] 


| 
! Indicators Operation | 
I | | | |lResulting 
1 | Factor | Factor Result! flindicators 
1 | i | 2 field | Jl+- 0 
Cl NxxNxxNxx | | | | | Il> < = +- Comments --+ 





0 | 4 | 2 | 3 | 4 | a) | 6 
123456789012345678901234567890123456 7890123456789012345678901254567890 


He ¥ # % % % H-“HRK HOR 
¢ ASCTIN EXTRN’SYS$ASCTIN’ 
¢ CALL ASCTIM 02 
¢ PARM TIMLEN WL 
¢C PARMD TIMFUF 23 
¢C PARMV 0 
_C¢ NO2 TIMBUF DSPLYTTY 
CEOB) 
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The following example calls two VAX/VMS System 
Services—SYS$CRELOG and SYS$GETMSG. The VAX/VMS System 
Service SYS$CRELOG sets on external indicators 3 and 7 to control the 
opening of files in a VAX RPG II program by calling SYS$CRELOG to 
define the logical name RPG$EXT_INDS. If the operation is unsuccessful, 
BUFFER receives the error message which SYS$GETMSG returns, and the 
program displays the error message. 
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This example also demonstrates a method for modifying the external 
indicators logical. The effect is that subsequent program runs will have 
the appropriate external indicators set on, depending on the value of the 
RPG$EXT_INDS logical. The external indicators in the program example 
below are not modified in the currently running program. See Chapter 7 
for information on modifying the external indicators in a SUEY: running 





program. 

0 { 2 3 | rn | 5 CO 6 | 7 ] 
1234567890123456789012345678901234567890123456789012345678901 2345678901 234567890 
FERROR DF 80 TTY _ 

C¥++ 

C* Call SYS$CRELOG to set on the external indicators 3 and 7. 
Ck-- . 

¢ MOVEL’RPG$EXT_’LOGNAM 12 

C MOVE ’INDS’ LOGNAM 

C MOVE °3,7’ STRING 3 

Cx 

C CRELOG EXTRN’ SYS$CRELOG’ 

C CALL CRELOG 99 
¢C PARMYV 4 

C PARMD LOGNAM 

C PARMD STRING 

C PARMYV 0 

C GIVNG RETVAL 

C¥++ 


C# If the call was not successful, 
C# call SYS$GETMSG to get the error text 


Cx#-- 
Cc 99 CALL GETMSG 
PARMY RETVAL 100 

¢ PARM LENGTH 90 WL 
C PARMD BUFFER 80 

¢ PARMV _ 0 

C PARMY 0 

¢C GETNSG EXTRN’SYS$GETMSG’ 

CX++ 

C* Display the error text 

CX-- 
C 99 BUFFER DSPLYERROR 

C¥++ 

a Set on an indicator to end the program 

t-~ 

¢ SETON LR 
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The following example calls a VAX/VMS Run-Time Library routine and 
a VAX/VMS system service. The VAX/VMS Run-Time Library routine 
LIB$CVT_HTB accepts as input an eight-digit hexadecimal value. The 
program calls the system service SYS$GETMSG to retrieve the error 
message text associated with the condition. 





0) | { | 2 | 3 | 4 | a) | 3) | 7 ‘| 
123456 7890123456 7890123456 7890123456 7890123456 7890123456789012345678901 234567890 

FERROR DF 80 TTY 

C++ 

Cx Prompt message 

Cx-- 

C MOVE ’x value: ’MESSAG 16 

¢C MOVEL’Enter ’ MESSAG 

C: MESSAG DSPLYERROR HEX 8 

C#++ 

C# Call LIB$CVT_HTB to convert to binary 

Ck-- 

C CALL CVTHTB 

C PARMV 

C PARM HEX 

C PARM VALUE. WL 

¢ CVTHTB EXTRN’LIB$CVT_HTB’ 

C¥++ 

Cx Call SYS$GETMSG to get the error text 

Cx-- 

¢ CALL GETMSG 

¢C PARMV VALUE 90 

C PARM LENGTH 90 WL 

C PARMD BUFFER 80 

C PARMV 0 

C PARMV 0 

¢ GETMSG EXTRN’SYS$GETMSG’ 

Cxt++ 

C* Display the error text 

C#-- 

¢C BUFFER DSPLYERROR 

Cx++ 

C# Set on an indicator to end the program 

Ck== 

C SETON LR 
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For additional information on coding considerations when using external 
routines, see the Introduction to VAX/VMS System Routines and the Guide 
to Creating Modular Procedures on VAX/VMS. 
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The Introduction to VAX/VMS System Routines contains the VAX Procedure 
Calling and Condition Handling Standard. The VAX/VMS Modular 
Programming Standard can be found in Appendix A of the Guide to 
Creating Modular Procedures on VAX/VMS. 


12.6 Examples of Calling Subprograms 


In addition to calling VAX/VMS Run-Time Library routines and system 
services, VAX RPG II programs can also call subprograms written in 
languages other than VAX RPG II. 


The following program calls a VAX COBOL subprogram and a VAX BASIC 





subprogram: 
0 | 4 | 3 | 4 | 3) | 3) | 7 | 
LEE Delo RE Eee ea 

Te { x % “* H--HEH HH 
Cx-- . : 

Cx++ 

C* The same parameter list is used by both calls 

Ck-- 

C PARAM PLIST 

C . PARM MESSAG 16 

Cx++ 

Cx Call the VAX COBOL program 

Cx-- 

C- MOVEL’RPG call ’MESSAG 

¢ MOVE ‘ed COBOL’ MESSAG 

C CALL ’COBOLi1’ PARAM 

C#t+ a 

Cx Call the VAX BASIC program 

une 

¢ MOVE ’BASIC’ MESSAG 

¢ CALL ’BASIC1’ PARAM 

Cx++ 

C* Set on an indicator to end the program 

Ce-- 

C SETON LR 


ZK-4657-85 


12-32 Calling System Routines from VAX RPG II 


The following example is the VAX COBOL subprogram: 


IDENTIFICATION DIVISION. 
PROGRAM-ID. COBOL1. 
DATA DIVISION. 
LINKAGE SECTION. 
01 MESSAGE-1 PIC X(16). 
PROCEDURE DIVISION USING MESSAGE-1. 
PO. 
DISPLAY MESSAGE-1. 
EXIT PROGRAM. 


The following example is the VAX BASIC subprogram. 


100 SUB BASIC1 (STRING Eeeater = 16 BY REF) 
200 PRINT MESSAGE 
300 END SUB 


12.7 Examples of Screen Handling with System Calls 


This section provides examples of VAX RPG II program fragments that 
perform screen handling using the VAX Terminal Data Management 
System (TDMS), the VAX Forms Management System (FMS), the VAX 
Screen Management (SMG$), and the CALL statement. Note that access 
to a subset of VAX FMS is integrated into the language using WORKSTN 
files, making it unnecessary to use the CALL statement. See Chapter 6 for 
details. 


VAX TDMS, VAX FMS, and VAX SMG$§ are designed to make it easier to 
develop interactive applications. Both VAX TDMS and VAX FMS provide 
utilities that let you define all the screen forms outside the VAX RPG II 
program. They also let you design forms by typing them directly onto 
the terminal screen. An example of a TDMS program is provided i in 
SYS$EXAMPLES:RPGTDMS.RPG. ; 


The following TDMS examples are part of the complete program example 
provided in SYS$EXAMPLES. 


NOTE 


If you use SYS$EXAMPLES:RPGTDMS.COM and get a TDMS 
TSS error that the form display failed, use the DCL command 

SET TERMINAL/DEVICE to set the device type (if pessine) to 
a device supported by TDMS. 
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The following example demonstrates the use of data structures and the 
COPY_CDD directive in a VAX RPG II program that calls TDMS. See 
Chapter 15 for more information on data structures and the COPY_CDD 


directive. 
1 | 2: Cd 3 | 4 | 5 | 6 | 7 | 





1) | 
123456 7890123456 7890123456 7890123456 78901 254567890123456 7890123456 7890125456 7890 





#4 nn eee) oo oer) HERR ER cree 
“aiaablans 1 88 EMPREC 
TEMPREC 


DS 
I/COPY_CDD 'CDD$TOP TDMS$EXAMPLES. EMPLOYEE. EMPLOYEE_RECORD’ 


CEOB) 





Press the PFe ke 
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The following example demonstrates the use of long character literals 
in an VAX RPG II program that calls TDMS. See Chapter 15 for more 
information on long character literals. 


Field length 


Control level 1 Decimal positions 
I | tHalf adjust (H) 
Indicators Operation 1 fl 
| | | [Resulting 
| Factor | Factor Result! Iilindicators 
| | | 2 field | Il+- 0 
Cl NxxNxXxXNxx1 | | | Il> < = +- Comments --+ 





a Sees Genie ern! a Sn Sa | 


123456 7890123456 7890123456 7890123456 7890123456 7890123456 7890123456 7890123456 7890 





* % ° & % H--HRE KH 
REQUES EXTRN’ TSS$REQUEST’ 
CALL REQUES . 99 
PARM CHAN 90 WL 
PARM LIBID 90 WL 
PARMD ss 


“EMPLOYEE INITIAL_REQUEST’ 
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For further information on VAX TDMS, see the following related 
documents: 


VAX TDMS Forms Manual 

VAX TDMS Request and Programming Manual 
VAX TDMS Application Programming Manual 
VAX TDMS Sample Application Manual 
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_ The following program segment is from a VAX RPG II program that calls 
VAX FMS t to display a form: 


Control level 
| 





7 
123456 7890123456789012345678901234567890123456 7890123456 7890123456 7890123456 7890 


1 Indicators Operation 

1 | | 

1 | Factor | Factor 

1 | i | 2. 
Cl NxxNxxNxx | | | | 

| 1 | 

HK % % x % 
C FCLRSH EXTRN’ FDV$CLRSH’ 
C MOVE ’FIRST ’ 
C CALL FCLRSH 
C PARMD 


Field length 
| 


Resultl 
field | 


FORM 
FORM 


Decimal positions 
IHalf adjust (H) 
| 


| 
| Resulting 
IVindicators 


11> < = +- Comments --+ 
| 


H--HRE KER. 
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For further information on VAX FMS, see Chapter 6 and the VAX FMS 


Reference Manual. 


Following is.a VAX RPG II program that calls VAX SMG§ routines. This 
program displays the word “Menu” beginning on line 2, column 5. 
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Field length 
Control level | Decimal positions 
| IHalf adjust (H) 


| 
| Indicators Operation I dl 
1 I | IJlResulting 
1] Factor | Factor Result! !lindicators 
1 | 1 | 2 field | [I+ -0 
Cl NxxNxxNxx | | | | 1 Ite < = +- Comments --+ 


| 4 | 5 | 2) | 7 | 


) | i | 2 
a es bes ed ae ed ee ee eee ee ee 
% H--HEK HR * 
CREPAS EXTRN’ SMG$CREATE_PASTEBOARD’ 
CREDIS EXTRN’ SMG$CREATE_VIRTUAL_DISPLAY’ 
PUTCHA EXTRN’SMG$PUT_CHARS’ 
PASDIS EXTRN’ SMG$PASTE_VIRTUAL_DISPLAY’ 





* 
* 
oe. 
*« 
= Ke 


Z-ADDO ZERO 90 
Z-ADD1 LINCOL 90 
Z-ADD2 LINE 90 
Z-ADDS COLUMN 90 


MOVE ‘Menu’ OUT 4 
* Create the pasteboard. 
CALL CREPAS 


C 

¢ 

C 

C 

C 

¢ 

C 

¢ 

C 

C 

¢ 

¢ PARM PASTID 90 WL 
C PARMV ZERO 

C PARM HEIGHT 90 WL 
C PARM WIDTH 90 WL 
Cx Create the virtual display. 

C CALL CREDIS 

C PARM HEIGHT RL 
C PARM WIDTH RL 
C PARM DISPID 90 WL 
C# Output the ‘Menu’. 

C CALL PUTCHA 

C PARM DISPID RL 
C PARMD OUT 

¢ PARM LINE RL 
C PARM COLUMN RL 
Cx Paste the virtual display. 

¢ CALL PASDIS 

C PARM DISPID RL 
C PARM PASTID RL 
C PARM LINCOL RL 
C PARM LINCOL RL 
C SETON LR 
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For further information on VAX SMG$ routines, see the VAX/VMS 
Run-Time Library Routines Reference Manual. 
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Chapter 13. 
Optimizing Your Programs 





The word “optimization” as used in this chapter, refers to the process of 
improving the efficiency of programs. The objective of optimization is to 
produce programs that achieve the greatest amount of processing with the 
least amount of time, memory, and secondary storage. 


13.1 Optimizing with Data Structures 


Using data structures to update files can improve the run-time perfor- 
mance of your programs. The following example updates a file with a 
data structure defined in an Input specification and used in an Output 
specification. 
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) | 1 | 2 | 3 1 4 | tl 6 [ooed 
123456 789012345678901234567890125456 7890123456 7890123456 78901234567890123456789 


0 
FOUT94A UD F 24 DISK 
FOUTS4B UD F 24 DISK 
IOUT94A =AA 
L 1 3 PN 
I 4 10 PNAME 
I 41 12 WHOUSE 
I 13. 17 COLOR 
I 18 20 WEIGHT 
I 22 240QTY 
IOUT94B AA 
I 1 24 DS94B 
IDS94B DS 
I 4 3 PNe 
I 4 10 PNAME2 
I if 12 WHOUS2 
I 43 17 COLOR2 
I 18 20 WEIGH2 
I 22 240QTY2 
DOUT94A E 
0 PN 3 
0 PNAME 10 
0 WHOUSE 12 
0 COLOR 17 
0 WEIGHT 20 
0 - QTY 24 
OOUT94B E 
0 DS94B 24 
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Note that the fields to be updated in the Output specification for file 
OUT94B are not listed a second time, as they would have to be without 
use of a data structure. Because the layout of the fields is described only 
once in the data structure, the results are. shorter code and a program less 
prone to error. Without a data structure, the fields must be described on 
both the Input and Output specifications. . . 


13-2 Optimizing Your Programs 


13.2 Optimizing with Adjacent Fields in Records 


VAX RPG II extracts adjacent fields from the record buffer with a single 
MOVE instruction and writes them back in the same way to save time. 
This optimization is performed only if data conversion is unnecessary. 
Therefore, you should keep the fields contiguous to avoid requiring 
multiple MOVE instructions. | 


13.3 Optimizing with Blank Factor 1 


If you use blank factor 1, you will have less code to write and your 
program will be less prone to error because you are not writing the same 
factor twice. The following example, which is part of the preceding 
example program, demonstrates this technique: | 





0) | 4 | 2 3 | 4 i 5 | Ls) | | 
123456 7890123456 78901234567890123456 7890123456 7890123456 7890123456 78901234567890 





I 22 240QTY2 

Cx Read records from update files. 

C READ OUT94A LR 

C NLR READ OUT94B 

Cx Update quantity to reflect the fact that 100 of each part came in. 
C NLR . ADD 100 QTY 

C NLR ‘ ADD 100 QTY2 

C* Write the updated records. 

C NLR EXCPT 
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13.4 Optimizing with the Asterisk Indicator 


The asterisk indicator (*) is used when you have multiple calculation 
specifications that are conditioned by the same indicators. There are two 
advantages to using the asterisk indicator. First, it saves you coding time 
and reduces errors, because multiple indicators do not have to be repeated 
in groups of Calculation specifications that are to be conditioned by the 
same indicator. Second, it improves run-time performance. 


Optimizing Your Programs 13-3 


If you do not use the asterisk indicator, groups of indicators must be tested 
on each Calculation specification, even if the same indicators are used to 
condition a group of Calculation specifications. With an * in column 

11, only a single test for each Calculation specification is needed to test 
whether the previous specification was executed. 


The * can be used in a similar fashion to condition output records and 
output fields. 


13.5 Optimizing File Performance 


You can control file access and improve file performance through optimiz- 
ing techniques discussed in this manual and in the Guide to VAX/VMS 
File Applications. The following optimizing techniques are discussed in 
Chapter 15 of this manual: 


e For information on the use of expansion factors to prevent bucket 
splitting and to improve search efficiency, see Section 15.3.24. 

e For information on file sharing, see Section 15.3.25. 

e For information on multibuffer count, see Section 15.3.21. 


¢ For information on longer block length for decreasing I/O processing 
time, see Section 15.3.9. 


e For information on multiblock count, see Section 15.3.14. 


For more information on optimizing techniques, the Guide to VAX/VMS 
File Applications provides pertinent information on tuning sequential, 
relative, and indexed files. That manual also describes optimizing file 
performance and processing in a VAXcluster, and offers performance 
recommendations. 
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Language Reference 


This part of the manual provides reference information on 
the primitives and constructs of VAX RPG II: 

e Language elements — 

e VAX RPG Il specifications 

e Operation codes 


Chapter 14 


VAX RPG II Language Elements 


This chapter describes the primitives or elements of a VAX RPG II program. 
These elements include the character set, the various data types, and the 
names that are defined and used to identify program constructs and certain 
parts of those constructs. 


14.1 VAX RPG Il Character Set 


VAX RPG II uses the full ASCII character set, including: 


¢ Uppercase letters A through Z, except for character literals and 
comment fields ; 


e Digits 0 through 9 
¢ Special characters (such as #, $, @) 


Appendix A contains the complete ASCII character set and character 
values. 
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14.2 VAX RPG II Data Types 


VAX RPG II input and output operations use the following data types 
that determine how many bits of storage compose a unit of data in a 
program, and how that unit is to be interpreted and manipulated at 
program execution time. 


VAX RPG II supports five different data types for input and output 
Operations: 

© Character . 

¢ Word binary numeric 

e Longword binary numeric 

e §=6©Packed decimal 

¢ Overpunched decimal 


This section describes each data type. 


14.2.1 Character Data Type 


Character data is a string of bytes containing ASCII codes as binary data. 
The length can be from 1 to 9999 bytes. The format of a character string 
is shown in Figure 14-1. 


NOTE 


In all subsequent diagrams, A represents the address of the first 
byte of the string and L represents the length of the string in 
bytes. 
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Figure 14-1: Format of a Character String 
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The address of a string specifies the first character of a string. The address 
XYZ is shown in Figure 14-2. 


Figure 14-2: Address of a String 
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14.2.2 Binary Data Type 
Binary data is stored as binary values in a word or longword. A word is 


two contiguous bytes, starting on an arbitrary byte boundary. The bits are 
numbered from the right (0 through 15). When interpreted as a signed 
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quantity, a word is a twos complement number with bits increasing in 
significance from bit 0 through bit 14, and with bit 15 designating the 
sign. A two-byte word supports up to four decimal digits. The largest 
number that can be represented by a word in VAX RPG II is 9999. A 
word data type is shown in Figure 14-3. 


Figure 14-3: Word Data Type 


15 0 
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A longword is four bytes, starting on an arbitrary byte boundary. The 
bits are numbered from the right (0 through 31). When interpreted as a 
signed quantity, a word is a twos complement number with bits increasing 
in significance from bit 0 through bit 30, and with bit 31 designating 

the sign. A four-byte longword supports up to 9 decimal digits. The 
largest number that can be represented by a longword in VAX RPG II is 
999,999,999. A longword datatype is represented in Figure 14-4. 


Figure 14-4: Longword Data Type 


31 . 0 
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14.2.3 Packed Decimal Data Type 


Packed decimal data is stored as a string of bytes. Each byte is divided 
into two 4-bit half bytes (nibbles), with one decimal digit stored in each 
half byte. The first, or most significant digit is stored in the high-order 
half byte of the first byte; the second digit is stored in the low-order half 
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byte of the first byte; the third digit is stored in the high-order half byte 
of the second byte; and so on. The sign of the number is stored in the 
low-order half byte of the last byte of the string. The number +123, in 
packed decimal format, is shown in Figure 14-5. 


Figure 14-5: Packed Decimal Data Type 
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A decimal 10, 12, 14, or 15 represents a plus sign, although 12 is used 
when the number is created as a result of a VAX arithmetic instruction. A 
decimal 11 or 13 represents a minus sign, although 13 is used when the 
number is created as a result of a VAX arithmetic instruction. 


The following formula can be used to determine the length in digits of a 
packed decimal field: 


number of digits = 2n - 1 
where n = number of bytes used 


See Section 15.6.15.4 for examples of selecting numeric data types in a 
VAX RPG II program. 


14.2.4 Overpunched Decimal Data Type 


Overpunched decimal data is a contiguous sequence of bytes in memory, 
with one decimal digit in a byte. Digits of decreasing significance are 
assigned to increasing addresses. The sign is superimposed on the last 
digit (trailing numeric string). 


All bytes of overpunched decimal data, except the least significant digit, 
must contain ASCII decimal digits (0 through 9). Table 14-1 lists the 
representation for all digits but the least significant digits. 
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Table 14-1: Overpunched Decimal Representation of All but 
the Least Significant Digits 


Sign Decimal Hexadecimal ASCII Character 
0 48 30 0 
1 49 31 1 
2 50 32 2 
3 51 33 3 
4 52 34 4 
5 53 35 5 
6 54 36 6 
7 55 37 is 
8 56 38 8 
9 57 39 9 


There are several variations of overpunched decimal format. Alternate 
forms of overpunched decimal format are accepted on input. The normal 
form of overpunched decimal format is generated on output. Valid 
representations of the digits and signs in each of the latter two formats 
(input and output) are shown in Table 14-2. 


Table 14-2: Overpunched Decimal Representations of Least 
Significant Digits and Signs 


Overpunched Decimal Format ASCII Characters 
Digit Decimal Hexadecimal Normal Alternate 
0 48 30 0 (1? 
1 49 31 1 A 
2 50 32 2 B 
3 51 33 3 Cc 
4 o2 34 4 D 
5 53 35 5 E 
6 54 36 6 F 
7 55 37 z G 
8 56 38 8 H 
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Table 14-2 (Cont.): 


Overpuached Decimal Format 
Hexadecimal 


Digit Decimal 
9 57 
-0 125 
-1 74 
-2 75 
-3 76 
-4 77 
-5 78 
-6 79 
-7 80 
-8 81 
-9 82 


39 
7D 
4A 
4B 


4C 


4D 
4E 
4F 
50 
51 
52 


Overpunched Decimal Representations 
of Least Significant Digits and Signs 


ASCII Characters 
Normal Alternate 


I 
}:! 


\o 


BO: SO 2 S ere Soe 


Figure 14-6 shows 123 in trailing numeric string format. 


Figure 14-6: Overpunched Decimal Data Type (123) 





ZK-1456-83 


VAX RPG Il Language Elements 14-7 


Figure 14-7 shows -123 in trailing numeric string format. 


Figure 14-7: Overpunched Decimal Data Type (-123) 





A+2 
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14.3 User-Defined Names 


A user-defined name is a named quantity that identifies items in a VAX 
RPG II program. These items include: 


Files—a file name is assigned to a file. 


Fields—a field name is assigned to a field in a program. You can use 
a field name in more than one field definition if each definition using 
that name has the same data type, the same length, and the same 
number of decimal positions. 


Arrays—an array name is assigned to an array. The first three charac- 
ters cannot be TAB. 


Tables—a table name is assigned to a table. The first three characters 
must be TAB. 


Labels—a label identifies the destination of a GOTO operation code. 
Subroutines—a subroutine name is assigned to a subroutine. 


PLIST—a PLIST name is assigned to a list of parameters to be passed 
to a subprogram. 

EXCPT—an EXCPT name can be used in factor 2 of the EXCPT 
operation code and in the Field name field of exception record Output 
specifications. See Section 15.8.5 for information on exception record 
types. 
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When defining a name, observe the following rules: 


The first character of a name must be one of the following: 
— Uppercase letters A through Z | 
— An underscore (_) 

— A pound sign (#) 

— A dollar sign ($) 


— Anat sign (@) 


The remaining characters of a name can be the uppercase letters A 
through Z, the digits 0 through 9, an underscore (_), a pound sign 
(#), a dollar sign ($), or an at sign (@). 


You must left justify names. 
You cannot embed blanks in a name. 


You cannot use a VAX RPG II special word as a name. See Chapter 9 
for information on special words. 


The maximum length of a name is six characters, except for a file 
name, which can be up to eight characters long. 


Every user-defined name must be unique. For example, a name 
assigned to a file cannot be used as a field name. 
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Chapter 15 


VAX RPG II Specifications 


VAX RPG II specifications are the major program element of the language 
and tell the computer what data to use, how to process it, and what to do 
with the results. This chapter provides general VAX RPG II information 
and a description of each VAX RPG II specification. 


The VAX RPG II specifications described in this chapter are as follows: 
e Control 
e File Description 


e Extension 
e Line Counter 


e =Input 
e Calculation 
¢ Output 


Each specification description includes the following information: 


e A brief explanation of the specification’s purpose 
e The specification’s format 
e A detailed explanation of each column 
— A brief explanation of the column’s purpose 
— A table listing valid entries for the column 
— An example of a typical use 
Use the information in this chapter for quick reference. For information 


on topics requiring a more detailed explanation, see the Table of Contents 
or Index. 
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Language Conventions and Format 


15.1 General Language Information 


This section provides a description of the notation conventions for VAX 
RPG II specifications, data fields that are common to all specifications, and 
special instructions to the language compiler. 


15.1.1 Notation Conventions 


This section describes the notation conventions of the specifications 
described in this chapter. 


Two rows of digits identify column numbers, as shown in the following 
example: 





Cel. Ae eo ee | ede ge eee fd 
123456 7890123456 7890123456789012345678901234567890123456 78901 2345678901 234567890 
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The arrow in the following example points to column 43. The vertical line 
above the first zero separates columns 30 through 39 from columns 40 
through 49; the vertical line above the second zero separates columns 40 
through 49 from columns 50 through 59. 


| 4 | 





01234567890 


ZK-4530-85 


Asterisks (*) in the dotted line below the two rows of column numbers 
indicate the beginning of fields that have values for the specification being 
described. Each field is terminated by another asterisk, by a dot, or by 
column 75. 


The positions of the asterisks are different for each specification. 


The asterisk in the following example indicates that you can enter a value 
in column 6. 
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The dots in the line below the two rows of column numbers identify fields 
_ that must be blank. 


2 





| 2 | 3 OI r 5 6. | 
ORG YECUSER. GCFECUSER. GUYECUSERC GL YECUISEREGCIECUSERL GUYESUSERE GPEC USERS GPEC) 


RRR RR REET ERMC RRS Per er or Ra ACR CI I Ae ee eT 


ZK-4455-85 


In the following example, dashes after an asterisk indicate a field that must 
contain numeric data. Numeric data must be right justified in the field. 
Blanks after an asterisk indicate a field that must contain alphanumeric 
data. Alphanumeric data must be left justified in the field. 





3 4 Nl 5 l 6 | 7 Nl 
EXC UCIECINER GCYECIBERCMYELISER, GYERUNERCUCIECUBER GCIECUSERE GUYELUSEACULYEEL) 
HX HREKRKKRK——— HK — — — HKRKR- KKK ¥—-—- — HK % eee for--- HN, HR OL, 


ZK-4456-85 


In the following example, the value 32 has been entered in columns 20 
through 23; the value 41 has been entered in columns 24 through 27; no 
value has been entered in column 28; the value 9 has been entered in 
columns 29 and 30; no value has been entered in column 31. 


r 2. | 
012345678904 


ZK-4457-85 


15.1.2 Common Fields 


This section describes fields that are common to all specifications. 
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15.1.2.1 Line Number 


You can associate a line number in columns 1 through 5 on each line of 
your program. Line numbers are optional, but can be useful in checking 
the sequence of lines. To check whether line numbers are in the proper 
sequence, you must specify the /SEQUENCE—CHECK qualifier to the 
RPG command. If you do not, VAX RPG II will ignore all line numbers. 
The absence of line numbers does not affect your program. 


Column Allowable 
Number Values Explanation 


1-5 Any number Associates a line number with the program line 


Additional Information 


If you specify the /SEQUENCE_CHECK qualifier to the RPG command 
and the line numbers are out of sequence, VAX RPG II will issue a 
warning compile-time error. 


15.1.2.2 Specification Type 


You must identify the type of specification in column 6 on each line of 
your program. 


Column Allowable 


Number Values Explanation 
6 H Control specification 
F File Description specification 
E Extension specification 
L Line Counter specification 
I Input specification 
C Calculation specification 
O Output specification 
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15.1.2.3 Comments 


You can use columns 75 through 80 to write comments about the program 
line. VAX RPG II ignores entries in columns 75 through 80. In other 
implementations of VAX RPG II, these columns are used for a program 
name. VAX RPG II uses the source file name as the name of the program. 


Column Allowable 


Number Values Explanation 
75-80 Any. character Documents the program line 
Rules 


e Blank lines can appear between any two specifications. VAX RPG II 
ignores blank lines. 


e A specification containing only a form feed can appear between any 
two specifications. Specifications containing only a form feed are 
treated like blank lines except in the listing file, where they cause the 
listing to skip to the top of the next page. 


Additional Information 


You can also use an entire specification to write a comment when you 
precede the comment with an asterisk (*) in column 7. You can do this 
with any type of specification. Any line with an asterisk (*) in column 7 
before the first double slash (//) or double asterisk (**) is considered a 
comment. 


15.1.3 Compiler Directing Statements 
You can include compiler directing statements in your program source file 


to access other files as information resources. You do this with the COPY 
and COPY_CDD directives as described in the following subsections. 
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15.1.3.1 COPY Directive 


The COPY directive allows you to copy one or more source files into the 
main source file during compilation. This feature can be used for copying 
in common subroutines, record definitions, or other useful information. 


The COPY directive can be followed by a modifier statement which 
supplies additional information on a preceding Input specification field. 
See Section 15.1.3.3 for the syntax and rules of modifier statements. 


If you specify the /SEQUENCE—CHECK qualifier, then the copied lines 
are sequence checked separately from the main source file. 


The COPY and COPY_CDD directive lines are always listed in the listing 
file. The copied lines immediately follow the COPY directive line in the 
listing. Each line is given a unique listing line number. A “C” is placed 
after the line number in the listing record to indicate that the line was 
generated by a COPY directive. There is still a single set of line numbers 
to mark the entire source file, after allowing for text that has been copied 
into the main source file. 


If a COMPILE command is issued from the VAX RPG II editor and 

an error is flagged within the compilation of a COPY or COPY_CDD | 
directive, the cursor is placed at the COPY directive, and the message is 
displayed on the message line. You must leave the VAX RPG II editor if 
you want to see the compiler source listing. 


The file SO.MUCH—TIME_AND_SO_LITTLE_TO_DO.RPG is copied 
in as a result of the following example: 


0 | 1 | 2 | 3 | 4 | a) | 6 | 
123456789012345678901234567890123456789012345678901234567890123456 78901 234567890 





HK * x % * K-~HEE HOH 
C/COPY ’SO_MUCH.TIMEAND_SO_LITTLE_TO_DO’ 
ZK-4458-85 


If multiple COPY directives are used in a program to define compile-time 
tables or arrays, the second and subsequent entries beyond the first COPY 
directive will be flagged as errors. For example: 


O/COPY ‘ARRAY1' 
0/COPY ‘ARRAY2' 


The second COPY directive is flagged as an error because a ** was 
recognized from the first COPY directive, and COPY directives cannot 
follow a ** or //. For detailed information, see Section 15.1.3. 
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The workaround for this is to use append:or plus lists on the RPG com- 
piler command. For detailed information on the RPG command, see 
Section 3.1.2. 


The COPY directive adheres to the following rules: 


e The COPY directive may appear anywhere within the source file 
before the first double slash (//) or double asterisk (**) line. It 
cannot appear after that, because the remaining lines do not contain 
a specification type. All lines after the first // or ** are treated as 
nonsource lines even if the // or ** occurs in a COPY¢file. 


¢ The COPY directive cannot appear within a long character literal. 

e There is-no limit on the number of copy directives in a program. 

e Copy directives cannot be nested. A file copied in cannot contain a 
COPY or COPY_CDD directive. See Section 15.1.3.2 for information 
on the COPY_CDD directive. 

e A COPY directive must appear on a line of its own and have the 
following syntax: 

— Column 6—must contain any valid saat type (not checked 
for sequence) 

— Columns 7 through 12—must contain COPY (note the blank space 
in column 12) 

— Columns 13 through 74—must contain the file specification 


enclosed in single quotes; the file specification does not need to 
start in column 13 


e A default file type of RPG is used 


15.1.3.2 COPY_CDD Directive 


Record definitions can be stored in the VAX Common Data Dictionary 
(CDD) and shared among VAX RPG II programs. You can extract these 
data definitions from the CDD and use them as field definitions on Input 
or Output specifications. If you change a definition in the CDD, you do 
not need to rewrite the program using the new definition; however, you 
must recompile the program to obtain the latest definition in the CDD. 
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The following example shows how to use the COPY_CDD directive to 
copy field information from the CDD on an Input specification: 


i] | 1 2 | 3 | 4 | 5 i ts) 7 
123456 7890123456 789012345678901234567890123456 78901 2345678901 2345678901234567890 
te % RX ¥--- #--- ¥--- AES, Steet Sete to RR KKK Cae 

I/COPY_CDD ‘RECORD. IN’ 





ZK-4459-85 


RECORD.IN is the CDD path name for a record description stored in the 
CDD. A path name must be enclosed in single quotation marks; note that 
the path name does not need to start in column 17. 


For information on CDD path names, see the VAX Common Data Dictionary 
User’s Guide. 


Any CDD name larger than six characters is truncated to the first six 
characters of the CDD name. If this truncated name has been used 
previously in a data structure, the last six characters of the CDD name are 
used. 


The CDD provides these RPG-specific features: NAME FOR RPG, EDIT_ 
WORD FOR RPG, and EDIT_CODE FOR RPG. For more information on 
attributes, see the VAX Common Data Dictionary Utilities Reference Manual. 


The following example and figure show field definitions entered in the 
CDD and the Input specifications that must be entered to extract the 
information. 


Using the DCL command CDDL, these field definitions are entered: 


DEFINE RECORD CDD$TOP. EXAMPLE. ADDRESS_RECORD 
ADDR STRUCTURE. 


STREET DATATYPE IS TEXT 
SIZE IS 30 CHARACTERS 

CITY DATATYPE IS TEXT 
SIZE IS 30 CHARACTERS 

STATE DATATYPE IS TEXT 


SIZE IS 2 CHARACTERS 
PHONE STRUCTURE. 


AREA DATATYPE IS NUMERIC RIGHT OVERPUNCHED 
SIZE IS 3 DIGITS 
NUMBER ' DATATYPE IS NUMERIC RIGHT OVERPUNCHED 


SIZE IS 7 DIGITS 
NAME FOR RPG IS 
P# 
END PHONE STRUCTURE. 
END ADDR STRUCTURE. 
END ADDRESS_RECORD. 
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In the VAX RPG II program, these Input specifications are entered: 





0 | 4 | Q | 3 | 4 | 5 | 6 7 | 


123456789012345678901 2345678901 2345678901234567890123456 789012345678901234567890 
H¥ nn ee 2 oer oor HEHEHE KR oer! 
IINFO AA 


I/COPY_CDD ‘EXAMPLE. ADDRESS_RECORD’ 
2K-4460-85 


The information is extracted from the CDD and parsed as though the user 
had entered the following: — 


0 4 2 3 | 4 | 5 | 6 ? | 





123456789012345678901234567890123456 7890123456 78901234567890123456 78901234567890 
% FRE ¥--- ¥--- HER HEH HK coer 
TINFO AA 
I {4 30 STREET 
I 31 60 CITY 
I 61 62 STATE 
I 63 72 PHONE 
I 63 650AREA 
I 66 720P# 


ZK-446 1-85 


15.1.3.3 COPY_CDD Directive Modifiers 


To include indicators on input fields copied from the CDD you must enter 
a modifier statement after the COPY_CDD directive. You can modify 
any field in the current record including those copied from the CDD. The 
following fields can be modified: 


¢ Control-level indicator 
¢ Matching fields 

e Field-record-relation 

© Field indicators 
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Rules 

e A modifying statement is distinguished from other specifications by an 
ampersand (&) in column 7. 

e Only specifications that define fields can be modified. 


e As many modifiers as desired can be specified in one modifier specifi- 
cation. 


¢ The same field can be modified by multiple modifiers. 


e A field specification must be syntactically valid before and after 2 a 
modifier is applied. 


A modifier can be used to add an indicator where there was none in 
the original specification. The following example shows a control-level 
indicator set on the AREA field in the program: 





0 | 4 | 2 | 3 | 4 | 4) mes | 
12345678901 23456 7890123456 7890123456789012345678901253456789012345678901234567890 
# % HRE H--- Rem RO p X¥—-——k-—HRE RR RN KH ies 
TINFO AA . 
I/COPY_CDD ’EXAMPLE.ADDRESS_RECORD’ 
I& AREA Li 
2K-4462-85 


The field AREA is treated as if it had been specified with an L1 indicator 
in the control-level indicator field, that is, as if the specification had been 
as follows: 


4 | 4) | a) | 7 





0 | 4 | Fa | 3 | 
seen Reo 0 82) er eS 8 0 Oe ee ee be 212 
I 63 650AREA Li © 


2K-4463-85 
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A modifier can be used to supersede a previously specified value. You can 
also blank a field by entering an ampersand (&) as the first character of 
the desired field and leaving the rest of the field blank, as in the following 
example: . 





) | | | 2 | 3 | 4 | 5 | ) | 7 | 
1234567890123456789012345678901234567890123456 7890123456 7890123456 78901234567890 
| RR He RRR H--- ¥--- #--- PS, teateateat Seteeteed £2 a a a 

IMSLI27 01 1CA 
I/COPY ’MSL27A’ 
I8 FLDA & 
ZK-4465-85 


The previous example assumes that the file to be copied (MSL27A.RPG) 
contains the following specification: 


0 | 1 | 2 I 3 i 4 | 5 | 6 | 7 | 





ERLE EEUS ER, CEYCENU ERE REYEE ERE STEEL DERLELYES I CAL GLYEE) PERL ELYAEI SERLELYEELY 
ets ee to fe f ore 
I 6 6 FLDA O1 





ZK-4464-85 


In the example, FLDA is treated as if no field-record-relation indicator is 
given, that is, as if the Input specification is as follows: 





0 I 4 | é | 3 | 4 | 5 | 6 | a | 
123456 7890123456 7890123456789012345678901234567890123456789012345678901234567890 
HX HRRK Hemme EM p RRMA R-— KE # RRR RHE eae 
I 6 6 FLDA 
ZK-4466-85 


Modifiers can apply to all field definitions that follow the record containing 
the last COPY or COPY_CDD directive. In the preceding example, if 
FLDA occurred several times in the copied file, each occurrence would be 
modified. 
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If the source program looked like the following example, then only 
occurrences of the FLDA field associated with the second COPY directive 
would be modified. 


| 2 | 3 | 4 | 4) | 6 7 | 





YW) i 
1234567890123456789012345678901234567890123456 7890123456 789012345678901 234567890 
HR % RHE H~--- %#--- ¥--- 2 RR —-¥-—-— KX RRR EHR eee 
IMSLI27 AA Of 
I/COPY ‘MSL27A’ 


I BB 02 
I/COPY ‘’MSL27A’ . 
18 FLDA & 


ZK-4467-85 


When a modifier specification is not preceded by a (COPY directive, all 
previous input fields can be modified. 
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15.2 Description 


The Control specification allows you to do the following: 


e Assign a character other than the default (a dollar sign ($)) as the 
currency symbol 


e Specify the notation for numeric fields, edit codes, and UDATE 
¢ Specify an alternate collating sequence 
e Check the alignment of printed forms 


e Specify the program name that can be used with WORKSTN files to 
determine which forms library to use 


A Control specification is not required and should be used only when you 
need to define the use of one or more items described in the previous list. 
Use only one Control specification in a program. 


15.2.1 Control Specification Format 


The format of the Control specification is as follows: 


Currency symbol 

Inverted print (DIJ) 

| Alternate collating sequence (SE) 
| | 4P forms position (1) 
| | I 
| 





2 3 4 | 5 1 6 4 Pe eed 
123456 7890123456 7890123456789012345678901254867689012345678901254867890125486 7890 
RKeaae #@eseacnes %, Round seeseepepopueupsppenuesee"t@teueepespeespenenanespeoeneeuesetupeuenpeapespae” aeanuee 


ZK-4468-85 


15.2.2 Specification Type 


Use column 6 to identify the type of specification for every program line. 
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Column Allowable 


Number Values Explanation 
6 H Indicates that this program line is a Control specifi- 
cation 


15.2.3 Currency Symbol | 


Use column 18 to specify a character other than the dollar sign ($) to 
represent the currency symbol. | 


Column Allowable 
Number Values Explanation 


18 Blank Uses the dollar sign ($) as the currency symbol. 
The dollar sign is the default. 


Character Uses the character you specify instead of the dollar 
sign ($) for the currency symbol. 


You can use any character for the currency symbol except zero (0), 
asterisk (*), comma (,), ampersand (&), decimal point (.), minus sign 
(-), C(C), and R (R). 


15.2.4 Inverted Print 


The inverted print feature allows you to format your program output to 
conform with a variety of notation conventions. For example, using the 
United States convention for expressing a number with thousands and 
decimals, a number could be 12,345.67; the same value could be correctly 
expressed as 12.345,67 using other conventions. Use column 21 to specify 
the notation the printer uses for numeric fields, edit codes, and UDATE. 
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Column Allowable 
Number Values 


21 Blank 


15.2.5 Alternate Collating Sequence 


Control Specification (H) 


Explanation 


Uses a period as the decimal notation and a comma 
as the thousands separator in numeric literals and 
edit codes (for example, 1,234.56 and .56). Uses a 
slash (/) as the separator for the Y edit code; uses 
the mm/dd/yy format for UDATE (for example, 
07/04/76). See Section 15.8.14 for information 

on edit codes. See Chapter 9 for information on 
UDATE. 


Uses the same format as the BLANK option for 
numeric literals and edit codes. Uses a slash (/) as 
the separator for the Y edit code; uses dd/mm/yy 
format for UDATE. 


Uses a comma as the decimal notation and a period 
as the thousands separator in numeric literals (for 
example, 1.234,56) and edit codes. Uses dd/mm/yy 
format for UDATE; decimal points separate the day, 
month, and year elements (for example, 24.03.83). 


Uses the same format as the I option for UDATE, 
numeric literals, and edit codes with the following 
exception: writes a zero to the left of the comma 
when the field contains only a fraction (for example, 
0,56). 


Use column 26 to specify the collating sequence you want VAX RPG II to 
use when comparing character fields using the COMP operation code and 
when checking the sequence of matching fields. 
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Column Allowable 
Number Values 


26 Blank 


E 


Explanation | 

Uses the ASCII collating sequence. See Appendix 
A for the ASCII character set. 

Uses the EBCDIC collating sequence. See 
Appendix A for the EBCDIC character set. 


Uses a user-defined collating sequence. See 
Appendix A for the ASCII characters and their 
hexadecimal values. 


To define a collating sequence that is different from the standard ASCII 
or EBCDIC sequences, you must specify the hexadecimal value of each 
character whose position in the sequence you want to change, as follows: 


¢ Specify S in column 26 of the Control specification. 


¢ Include the specification for ALTSEQ records after the Output specifi- 
cation, but before any compile-time table and arrays, if used. 


e Precede the ALTSEQ records with double slashes (//) and a blank or 
double asterisks (**) and a blank in columns 1 through 3. 


e Specify the entries in the following table. 


Column Allowable 
Number Values 


1-8 ALTSEQbb 

9,10 Hexadecimal 
value 

11,12 Hexadecimal 
value 


Explanation 


Indicates that you are specifying an alternate 
collating sequence. Note that bb represents two 
blanks. 


Specifies the hexadecimal value of the character you 
want to change. 


Specifies the new hexadecimal value of the char- 
acter whose position in the collating sequence you 
want to change. 


Repeat this sequence of hexadecimal numbers up to column 80 for ad- 
ditional changes. The first blank space in an ALTSEQ record terminates 
the ALTSEQ entries for that record. The rest of the line can be used for 


comments. 
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In the following example, columns 9 and 10 and 13 and 14 contain the 
hexadecimal value of the character to be changed, and columns 11 and 12 
and 15 and 16 contain the new hexadecimal value of the character. In the 
following collating sequence, VAX RPG II changes the uppercase Z (5A) to 
an uppercase A (41) and the lowercase w (77) to an uppercase J (4A). 


0 4 2 | 3 4 | 5 | 3) | fj | 





1234567890123456 78901234567890123456 78901234567890123456789012345678901234567890 
x 


// 
ALTSEQ 5A41774A 
ZK-4469-85 


15.2.6 Forms Position 


Use column 41 to check the alignment of printed output on a nonstandard 
form. 


Column Allowable 


Number Values Explanation 
41 Blank Specifies no forms-positioning check 
+ if Checks the forms positioning by printing the first 
output line 


This entry is optional and valid only for a nonspooled device. 


Additional Information 


When you specify forms positioning, the printer outputs the first line. 
Then, VAX RPG II asks the following question for each printer output file 
in the order that the first lines are output: 


Is forms positioning correct? 
Yes, type Continue, No, type Retry: 


If you type CONTINUE, the program will print the second output line, 
and so on, until all lines are output. If the forms are not correctly posi- 
tioned, realign the form, and then type RETRY. VAX RPG II will print the 
first line again so that you can determine whether the form is positioned 
correctly. 
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15.2.7 Forms Library 


Use columns 75 through 80 to indicate the VAX Forms Management 
System (VAX FMS) forms library if the continuation line option FMTS in 
the F specification is not to be included in the WORKSTN file specification. 


15. 2. 8 Example 


In the following example, these control characteristics are defined: 


Program line is a Control specification 
Currency symbol is a pound sign (#) 
VAX RPG II uses 


— Acomma (,) as the decimal notation for numeric literals and edit 
codes 


— A period (.) as the thousands separator for numeric literals and 
edit codes 


— The dd.mm.yy format for UDATE 
Collating sequence is EBCDIC 
Forms-positioning check is not required 


Currency symbol 
Inverted: print (DIJ) 
| Alternate collating sequence (SE) 


| | {P forms position (1) 
| | | 
| 





H | | 
o | Lr o2 a ee a 
1234567890123456789012345678901254567890123456 7890123456 7890123456 7890123456780 
Meceteeee eee M here eMereersencsn ees Meceeeseenen eens nenenesennaeneenes 
H #Io€E 
ZK-4470-85 
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15.3 Description 


The File Description specification describes the following attributes of each 
file you use in your program: . 
e File Description specification format 

e Specification type 

# File name 

e File type 

_@ ~ File designation 

e End-of-file 

e Sequence 

e File format 

e Block length 

e Record length 
¢ Mode of processing 
e Key length 

e Record address type 

e File organization or additional input/output area 
¢ Overflow indicators 

° Key location 
e Extension code 

e Device code 
e Symbolic device 

¢ Tape label 

e File Description specification continuation lines 
¢ Core index | 
e File addition and unordered output 

e Expansion factor | 

¢ File sharing. 

° Tape rewind 
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e = File condition 
e Example 


15.3.1 File Description Specification Format 


The format of the File Description specification is as follows: 


Mode (LR) 
IKey length 
Type (IOUDC) II Record address type (APIB). Addtn(AU) 
IDes(PSRCTDF)I1 lOrganization (IT,1-9) JExpand 
H1EOF (E) 1! [10verflow indicator Continue (K) [iShr(SR) 
111Seq (AD) It TIl Key location lOpt Entry Ill Rewnd 
File LITIFmt (FV) TE TEE |) Extension (EL)II | Vit | 
name HITTIBIk Rec II TIl |) = =(Device Symb Tape Core III [File 
| Hilltlen len Il Tll |) = =lcode dev label index 11! Icond 
Oe ee Hie 
1 


| 








EE ha RRR 8 ooo 


ZK-447 1-85 


15.3.2 Specification Type | 


Use column 6 to identify the type of specification for every program line. 
Note that F specification continuation lines contain blanks in columns 7 


through 52. 
_ Column Allowable 
Number Values Explanation 
6 F Indicates that this program line is a File Description 
specification 


15.3.3 File Name 


Use columns 7 through 14 to identify the files you use in a VAX RPG II 
program. 
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Column Allowable 


Number Values Explanation 
7-14 File name Identifies the file 
Rules 


¢ The number of files you can open depends on the open file quota set 
by your system manager. To determine the number of files you can 
open in a VAX RPG II program, type the SHOW PROCESS/QUOTA 
command and look for the number to the right of open file quota :. 

e The specification options explained in Sections 15.3.4 through 15.3.26 
apply to the file you identify in columns 7 through 14. 


e VAX RMS uses the file name as the default file specification string. 
See Chapter 8 for information about how VAX RPG II uses the file 
name field and the symbolic device field to generate the VAX/VMS 
file specification. 

e VAX FMS uses the file name as part of determining the form library 
name to be used for WORKSTN files. See Chapter 6 for additional 
information. 


15.3.4 File Type 


Use column 15 to specify the file type which defines how VAX RPG I 
processes the records in the file. 


Column Allowable 


Number Values Explanation | 
15 I Designates an input file. VAX RPG II reads the 


records from an input file and uses these records 

as data. These records must be defined in Input 
specifications unless column 16 contains R or T. 
Input files can reside on disk or tape, or can be read 
from a terminal or from cards. 


O Designates an output file. The program writes or 
prints the records of an output file. These records 
must be defined in Output specifications unless this 
is a table output file. Output files can be written to 
a printer, disk, tape, or terminal. 
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Column 
Number 


Allowable 
Values 


U 


15.3.5 File Designation 


Explanation 


Designates an update file. Update files must reside 
on disk. VAX RPG II can read, change, and write 
records in an update file. The records in these 
files must be defined in the Input and Output 
specifications. 


Designates a display input or output file. Use 
display files to accept input from a terminal or to 
display output on a terminal. You must complete 
a Calculation specification to define the fields you 
want to display using the DSPLY operation code. 
See Chapter 16 for information on the DSPLY 
operation code. 


Designates a combined input/output file. A com- 
bined file must have a device code of WORKSTN. 


Use column 16 to specify file designation which defines the order of 
processing files. See Chapter 8 for information on processing files. 


Column 
Number 


16 
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Allowable 
Values 


Blank 
P 


Explanation | 
Specifies a nonchained output file or a display file. 


Specifies a primary file. You can use only one 
file as the primary file. It can be an input or an 
update file. In multifile processing, the primary 
file determines the order of record selection; in 
single file processing, the primary file provides all 
input records. If a primary file is not specified and 
one or more secondary files are specified, the first 
secondary file is assigned as the primary file. If no 
primary or secondary files are specified, you must 
provide an exit for your program by setting on the 
last-record (LR) indicator. 


Column 
Number 


Allowable 
Values 


S 


File Description Specification (F) 


Explanation 


Specifies a secondary file. A secondary file can 
be an input or an update file. See Chapter 8 for 
information on processing secondary files. 


Specifies a record-address file. A record-address file 
indicates which records to process and the order 

in which they are to be processed. This file must 
be associated with a file defined in an Extension 
specification. See Chapter 8 for information on 
record-address files. 


Specifies a chained file. A chained file resides 

on disk and can be used as an input, output, or 
update file. You use the CHAIN operation code 

in the Calculation specification to randomly read 
records from a chained file. You use an output 
chained file to add records to a direct file. The 
CHAIN operation positions the file before VAX 
RPG II writes each record. See Chapter 16 for more 
information on chained files. 


Specifies a preexecution-time table or array. You 
must enter, in columns 11 through 18 of the 
Extension specification, the name of the file that 


_ contains the data from which you want to load the 


table or array. See Chapter 10 for information on 
tables. See Chapter 11 for information on arrays. 


Specifies a demand input or update file. You can 
use the READ operation code in the Calculation 
specification to sequentially access the records in a 
demand file. See Chapter 16 for more information 
on using the READ operation code to access records 
from demand files. 


Specifies a full-procedural input or update file. You 
can use the READ and/or CHAIN operation code in 
the Calculation specification to sequentially and/or 

randomly access the records. 
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15.3.6 End-of-File 


Use column 17 to specify end-of-file that indicates whether the program 
can end before VAX RPG II processes all the records in the file. 


Column Allowable 
Number Values Explanation 


17 Blank Causes the program to finish reading all the records 
from every primary and secondary file before 
ending, if column 17 is blank for all primary and 
secondary files. If column 17 is not blank for all 
primary and secondary files, VAX RPG II may or 
may not process all the records in this file (the 
file described in this specification). If column 17 
is blank for all primary and secondary files, VAX 
RPG II processes all the records in this file (the file 
described in this specification). 


E Causes the program to finish reading the records 
in the file before ending the program, regardless of 
the presence of other files. You can use this option 
for input or update files as primary, secondary, or 
record-address files. You cannot use this option on 
a file being processed by a record-address file. 


When you specify E in column 17 for the primary 
file, and there are matching records in the primary 
and secondary files, VAX RPG II reads and pro- 
cesses any records in the secondary file that match 
the last record of the primary file before ending the 
program. 


15.3.7 Sequence 


Use column 18 to specify ascending or descending sequence to check 
matching fields. See Chapter 8 for information on matching fields. 
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Column Allowable 
Number Values 


18 Blank 
A 
D 
Rules 


File Description Specification (F) 


Explanation 


Indicates that the program contains no matching 
fields or, if it does, assumes the same value as 
specified for a previous primary or secondary file. 
If the program contains matching fields and you 
do not specify a sequence for any file containing 
matching fields, VAX RPG II assumes an ascending 
order. 


Checks matching records for ascending order. 


Checks matching records for descending order. 


e This entry applies only to primary or secondary files with matching 
fields. See Chapter 8 for more information on primary and secondary 


files. 


e This entry must be the same for each file you process with matching 


fields. 


15.3.8 File Format 


Use column 19 to specify file format. File format specifies whether the 
records in the file are all the same length, or whether they can be of 
different lengths. You can save processing time if all the records are the 
same length and each record is completely filled with data. If the records 
are not completely filled with data, you waste space. Variable-length 
records use space more efficiently, but take longer to process. 


Column Allowable 
Number Values 


19 F 
V 


Explanation _ 
Indicates that all records are the same (fixed) length 


Indicates that records can be of different (variable) 
lengths 
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e =6If you specify variable- -length records, VAX RPG II uses the highest 
value in columns 40 through 43 in the Output specification as the 
length for that record. 


¢ You must specify fixed- -length records for sequential files being pro- 
cessed as update files. 


Additional Information 

When a variable-length record is read, VAX RPG II fills the unused portion 
of the input buffer with spaces. Character fields with characters beyond 
the end of the record will be filled with spaces. Numeric fields with digits 
beyond the record will be filled with spaces. This condition will cause a 
run-time error, unless you use the /CHECK:BLANKS_IN-NUMERICS 
qualifier with the RPG command. A numeric field in packed decimal or 


binary format cannot extend beyond the end of the input record. If it 
does, unpredictable results will occur. 


15.3.9 Block Length 


Use columns 20 through 23 to specify the length of a block. Data is stored 
in physical records called blocks. A block is the smallest number of bytes 
VAX RPG II transfers in a physical READ or WRITE operation. 


In general, by specifying a longer block length, you decrease I/O pro- 
cessing time because more records will be available at any given time. 

For example, a program that loads a single key indexed file with ap- 
proximately 1700 80-byte records could result in an approximately 60% 
decrease in direct I/Os and a 40 to 50% decrease in elapsed time. This oc- 
curs when the block length is increased from 512 bytes (VAX RMS bucket 
size of 1 byte) to 4096 bytes (VAX RMS bucket size of 8). However, do 
not specify a block length that exceeds the Working Set Quota. To display 
the Working Set Quota, type the following: 


$ SHOW WORKING_SET 
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Column Allowable - 
Number Values Explanation 


20-23 Blank Uses the same entry for block length as the record 


length (columns 24 through 27) 


1-9999. Specifies the bucket size (in bytes) for those direct 
and indexed files being created on disk, or specifies 
the block length (in bytes) for files on tape 


For disk files, the block length you specify sets the VAX RMS bucket 
size parameter. VAX RPG II divides the block length you specify by 
512 and rounds the result to the next highest integer, if necessary. For 
example, if you specify a block length of 2048 bytes, the VAX RMS 
bucket size is 4 bytes. 


For disk files, the minimum block length is 512 bytes. 


For output tape files, the block length you specify sets the VAX RMS 
block size parameter. The block length must be either (1) equal 

to the entry in columns 24 through 27 (record length) of the File 
Description specification, or (2) an integer multiple of the record 
length. In either case, the block length cannot be greater than the 
maximum record length for the device. See your System Manager for 
the maximum record length. Block length is not needed for an input 
tape. If specified, it is ignored by VAX RMS. 


To make your tape compatible with non-DIGITAL systems, use the 
ANSI standard block length: less than or equal to 2048 bytes. 


Right justify this entry. 
Leading zeros can be omitted. 


Additional Information 


For additional information on quotas, see the VAX/VMS Guide to File 
Applications. 
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15.3.10 Record Length 


Record length specifies the length of each fixed-length record in a file, or 
the maximum length for variable-length records. 


Column Allowable 


Number Values Explanation 
24-27 1-9999 Specifies the number of characters in each record 
Rules 


e The record length for fixed-length records in an update file must be 
the same value you used to write the records. 

e = Right justify this entry. 

e¢ Leading zeros can be omitted. 


15.3.11 Mode of Processing 


Use column 28 to specify the method VAX RPG II uses to access records 
in a file. Your choice of processing method depends on the entries for file 
designation and file organization. Your choice of processing method for 
input and update files depends on the entries for the file type, the mode of 
processing, the record address type, and file organization. See Tables 15-1 
through 15-3 to select the correct value. 


Column Allowable 


Number Values Explanation 
28 Blank Accesses records sequentially, or accesses records © 


sequentially by key 
L Accesses records sequentially within limits 


Accesses records randomly using a relative record 
number or an index key, or using an ADDROUT 
file, or tells the program to load a direct file 


Additional Information 


Sequential processing reads the records in the order in which they were 
written. Sequential-by-key processing reads records from indexed files 
that are used as primary, secondary, or demand files. The key refers to 
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the index, which is read in ascending order. Sequential-within-limits 
processing reads records in one of two ways: 
e Specifying a range of records to be read. 


¢ Using the SETLL operation code in the Calculation specification to set 
the lowest key for the records in a demand file. The program reads 
records with keys equal to or higher than the key you specify. 


Random processing reads records from chained files in one of the follow- 
ing two ways: 


¢ For sequential or direct files, records are accessed by their relative 
record number. A relative record number identifies the position of a 
record relative to the beginning of the file. 


e For indexed files, records are accessed by their index key values. 
ADDROUT file processing uses the ADDROUT file generated by 
SORT/MERGE. The ADDROUT file contains binary record numbers 


that correspond to the addresses of records; therefore, the records to be 
read are located by their addresses. 


Files on devices other than disk can be accessed only sequentially. 


For input or update primary, secondary, or demand files that reside on 
disk, you can use the entries listed in Table 15-1. 
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Table 15-1: Modes of Processing for Primary, Secondary, 
and Demand Files 





File Allowable Allowable 
Organization Access Modes Entries 
Column: 
16 28 31 32 
Sequential Sequential P b b b (b or 1-9) 
S b b b (b or 1-9) 
D b b b (b or 1-9) 
F b b b (b or 1-9) 
Direct By ADDROUT P R I b (b or 1-9) 
file S R Nt b (b or 1-9) 
Indexed Sequential P b b b 
5 b b b 
D b b b 
F b b b 
By ADDROUT P R I I 
file S R I I 
Legend 


P—Primary file 

S—Secondary file 

I—Indexed file 

D—Demand file 
F—Full-Procedural file 

b—Blank 

R—Random 

L—Sequential within limits 
A/P—Alphabetic or Packed keys 
A/P/B—Alphabetic, Packed, or Binary keys 
1-9—Additional areas 
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Table 15-1 (Cont.): Modes of Processing for Primary, 
. Secondary, and Demand Files 


File Allowable Allowable 
- Organization Access Modes __ Entries 
Column: 
. 16 28 31 32 
Sequential P b A/P/B I 
by key S b A/P/B I 
D b A/P/B I 
F b A/P/B_ iI 
Sequential P L A/P I 
within S L A/P I 
limits D L A/P I 
F L A/P I 
Legend 


P—Primary file 

S—Secondary file 

I—Indexed file 

D—Demand file 
F—Full-Procedural file 

b—Blank 

R—Random 

L—Sequential within limits 
A/P—Alphabetic or Packed keys 
A/P/B—Alphabetic, Packed, or Binary keys 
1-9—Additional areas 
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For record-address files, you can use the entries listed in Table 15-2. 


Table 15-2: Modes of Processing for Record-Address Files 


File Allowable Allowable 
Organization Access Modes Entries 
| Column: 
16 28 31 32 
Sequential Sequential R b b b 
Direct Sequential” R b I T 


1 indicates a record-limits file 


2 Indicates an ADDROUT file 
Legend 

I—Indexed file 

T—Table 


b—Blank 
R—Random 
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For input or update chained files, you can use the entries listed in 
Table 15-3. 


Table 15-3: Modes of Processing for input or Update 
Chained Files 


File Allowable Allowable 
Organization Access Modes Entries 
Column: 
16 28 31 32 
Sequential Random, by C R b b 
or Direct relative record F R b b 
number 
Indexed Random, by key C R A/P/B I 
F A/P/B I 
Legend 
I—Indexed file 
. C—Chained 
F—Full-Procedural file 
b—Blank 
R—Random 


A/P/B—Alphabetic, Packed, or Binary keys 
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In the following example, the program accesses an indexed file as a 
demand file and three update chained files. 





Mode (LR) 
| IKey length 
Type (IOUDC) 11! Record address type (APIB) Addtn(AU) 
IDes(PSRCTDF) 11] lOrganization (IT, 1-9) 1Expand 
I1EOF (E) 11 |lO0verflow indicator Continue (K) | 1Shr(SR) 
111Seq (AD) Jl Itt Key location lOQpt Entry Ill Rewnd 
File PETEFmt CFV) Tl Tl | Extension (EL) IT | Hit | 
name TTITIBIK Rec HI] Ut! | = 'Device Symb Tape Core III IFile 
| littllen len ft] ttl | = teode dev label index III lcond 
ee Hl tat Ht 
| 1 | 2 I 5) 
0 
FINDEXi ID F 18 5Al 5 DISK 
FCHAIN’ UC F 24R DISK 
FINDEX2 UC F 24R SAI 1 DISK 
FCHAIN2 UC F 24R DISK 


ZK-4472-85 


15.3.12 Key Length 


Use columns 29 and 30 to specify key length. Key length indicates the 
length in bytes of one of the following: 


e The index keys in an indexed file 
e The index keys in a record-limits file 
e The addresses in an ADDROUT file 


Column Allowable 


Number Values Explanation 
29,30 Blank Indicates a sequential, direct, or display file 
1-99 Specifies the length of the record key for an indexed 


file or a record-address file 


e You must use a value of 6 for the length of the record addresses in an 
ADDROUT file. 


e = Right justify this entry. 
e Leading zeros can be omitted. 
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In the following example, the program reads a chained indexed file. The 
length of the record key is three bytes. 


Type (IOUDC) II 


|Des(PSRCTDF) 1 | 
IIEOF (E) 


File 
name 





FINDEX IC F 


15.3.13 Record Address Type 


HRM AH RRA REE RoW BE % Pe eee HEE, HH 
24R SAI i DISK 


lcond 
Ltd 





Mode (LR) 
[Key length 
Record address type (APIB) Addtn( AU) 
[Organization (IT,1-9) [Expand 
1] tlOverflow indicator Continue (K) I1Shr(SR) 
I] Tit Key location lQpt = =Entry Til Rewnd 
11 Tit t Extension (EL)I1 | Hil | 
I} tll | (Device Symb Tape Core III IFile 
1} tll | = leode dev label index II! 
amAER , ‘a 


I. ] Po he 
4 | 





ZK-4473-85 


Use column 31 to specify record address type. Record address type helps 
define the mode of processing. See Table 15-2 to select the correct value. 


Column 
Number 


31 


Allowable 

Values Explanation 

Blank Uses relative record numbers to process sequential 
and direct chained files, or reads records sequen- 
tially from an input or update file, or creates or 
adds records to a sequential output file 

A Processes or loads indexed files according to the 
record keys in alphanumeric format 

P Processes or loads indexed files according to record 
keys in packed format 

B Processes or loads indexed files according to record 


keys in binary (word or longword) format 


Processes the file according to an ADDROUT file, 
or identifies an ADDROUT file 
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15.3.14 File Organization or Additional Input/Output Area 


File organization specifies how records are arranged in a file. Additional 
I/O allows you to specify the number of I/O areas. Both attributes work 
in conjunction with the mode of processing. See Tables 15-2 and 15-3 to 
select the correct value. 


Column Allowable 


Number Values Explanation 
32 Blank Indicates a sequential or direct file, using one I/O 
area 
I Indicates an indexed file 
T Indicates an ADDROUT file 
1-9 Indicates the number of I/O areas for a sequential 


or direct file 


Additional Information 


For sequential files, VAX RPG II adds 1 to the Additional I/O area value 
you specify in column 32. VAX RPG II uses the value for Additional I/O 
to set the VAX RMS multiblock count in the Record Access Block (RAB). 


See the Guide to VAX/VMS File Applications for information about multi- 
block count and for optimizing file performance. 


15.3.15 Overflow Indicators 


Use columns 33 and 34 to specify an overflow indicator. You can use an 
overflow indicator to specify a page break before or after certain lines are 
printed. See Chapter 9 for information on overflow indicators. 


Column Allowable 


Number Values Explanation 
33,34 Blank Specifies no overflow indicator 
OA-OG, OV Specifies an overflow indicator to condition output 


lines when an overflow occurs 
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e You can use an overflow indicator to condition only printer output 
files. 


e You can assign only one overflow indicator to a file. If you have more 
than one printer output file and you want to use an overflow indicator 
to condition each file, you must specify a unique overflow indicator 
for each file. 


15.3.16 Key Location 


Use columns 35 through 38 to specify key location. Each record in an 
indexed file has a key field that VAX RMS uses to locate records. This key 
field can be anywhere in the record, but must be in the same location for 
each record in the file. Key location specifies where to find the key field in 
the record. . 


Column Allowable 





Number Values Explanation 

35-38 Blank Indicates that the file is not indexed 
1-9999 Specifies the location of the key field 

Rules 


e = Right justify this entry. 
e Leading zeros can be omitted. 


15.3.17 Extension Code 


Use column 39 to specify the extension code that causes VAX RPG II 

to read either the Extension or the Line Counter specification for more 
information about the file. You must complete an Extension specifica- 
tion for tables, arrays, and record-address files. You can complete a Line 
Counter specification for a printer output file. The Line Counter specifica- 
tion specifies the length of the printed page and defines the overflow line 
number. 
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Column Allowable 
Number Values 


39 Blank 
E 


L 


15.3.18 Device Code 


Explanation . 
Specifies no Extension or Line Counter specification 


Causes VAX RPG II to read the Extension specifica- 
tion for the file 


Causes VAX RPG II to read the Line Counter 
specification for the file 


Use columns 40 through 46 to specify the device code that indicates on 
what type of device the file is stored. 


Column Allowable 
Number Values 


40-46 Blank 
DISKXXX 


TAPEXXX 


PRINTXX 


TTYXXXX 


READXXX 
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Explanation 
Specifies the default disk device. 


Specifies a disk device where X is any character. 
Disk can be specified for sequential files but is 
required for indexed and direct files. Disk is the 
default device. 


Specifies a tape device for sequential files only. X 
can be any character. 


Specifies a print device for an output file. X can be 
any character. 


Specifies a terminal device for a display file or a 
sequentially processed input or update file. X can 
be any character. 


Specifies a card reader for sequentially processed 
input files. X can be any character. 


To use a card reader, you must specify I in column 
15 and P, S, T, or D in column 16. Also, leave 
columns 28 through 38 blank. 


File Description Specification (F) 


Column Allowable 
Number Values Explanation 


WORKSTN Specifies the mechanism by which many VAX 
FMS form capabilities can be accessed from a VAX 
RPG II program. You must include a C for the 
file type when you specify WORKSTN as the file 
device. There can only be one WORKSTN file in a 
program. See Chapter 6 for additional information. 


Rules 
Left justify this entry. 


Additional Information 


If you specify a device name other than one of the allowable values, 

VAX RPG II accepts it, but issues a warning message at compile time. 
VAX RPG II assumes a disk device, unless you specify D in column 15, in 
which case VAX RPG II assumes a terminal (TTY) device. 


For additional information on tape and disk operations, see the Guide to 
VAX/VMS Disk and Magnetic Tape Operations. 


15.3.19 Symbolic Device 


Use columns 47 through 52 to specify the symbolic device. The symbolic 
device can be a logical name for any device. VAX RPG II uses the sym- 
bolic device as the file name string. VAX RMS uses the file name string 
and the default file name string (the file name that appears in columns 

7 through 14) as the default name of a file being processed for input or 
output operations. See Chapter 8 for information on how VAX RPG II 
uses the symbolic device field (columns 47 through 52) and the file name 
field (columns 7 through 14) to generate the VAX/VMS file specification. 


Column Allowable 


Number Values Explanation 
47-52 Any Represents the symbolic device 
character 


The symbolic device name can contain up to six characters. It must not be 
specified for display or WORKSTN files. 
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15.3.20 Tape Label 


Use column 53 to identify the label for a magnetic tape. 


Column Allowable 


Number Values Explanation 
53 Blank Indicates that the magnetic tape has a standard 
VAX/VMS ANSI label 
S Indicates that the magnetic tape has a standard 


VAX/VMS ANSI label 


VAX/VMS can process only magnetic tapes with VAX/VMS ANSI labels. 


15.3.21 F Specification Continuation Lines 


F specification continuation lines can optionally follow a WORKSTN file 
specification. You can use continuation lines to indicate: 


e A VAX FMS forms library 
e A WORKSTN file information data structure 
e =6 An offset of forms on the screen 
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Column 
Number 


7-52 
53-59 


60-65 


60-67 


15.3.22 Core Index 


Allowable 
Values 


Blank 
FMTS 
INFDS 
SLN 


Field name 
or 

data 
structure 
name 


VAX FMS 
form 
library 
name 


File Description Specification (F) 


Explanation 

These columns must be blank. 

A VAX FMS library option. 

A WORKSTN file information data structure option. 
Offset of forms on screen option. 


Specifies the variable containing the number of 
lines to offset the forms on the screen for the SLN 
option. Or, specifies the WORKSTN file information 
data structure name. 


Specifies the VAX FMS forms library name for the 
FMTS option. 


Use columns 60 through 65 to set the VAX RMS multibuffer count in the 
Record Access Block (RAB). See the Guide to VAX/VMS File Applications 
manual for information about multibuffer count and for optimizing file 


performance. 
Column Allowable 
Number Values 
60-65 Blank 

1-9999 
Rules 


Explanation 


Specifies that the file is not indexed or that an 
indexed file has no core index 


Specifies the number of bytes to reserve for the core 
index 


e VAX RPG II divides the core index value by 512 and rounds the value 
to the next highest integer, if necessary. For example, if the core index 
is 513, the VAX RMS multibuffer count is 2. 
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If the operation results in an integer that is greater than 127, VAX 
RPG II uses 127 as the VAX RMS multibuffer count. 


¢ ~~ Right justify this entry. 
e Leading zeros can be omitted. 


15.3.23 File Addition and Unordered Output 


Use column 66 to specify file addition and unordered output. File addition . 
and unordered output determine how new records are added to a file. You 
can add records to sequential, direct, and indexed files that reside on disk. 
On tape, you must go to the logical end of the tape before adding records 
to a file; otherwise, new records would overwrite existing records. 


Column Allowable 
Number Values 


66 Blank, A, U 


For output files, you can choose one of the following entries. 


Entry Explanation 


Blank Creates an indexed file and adds records by primary key, or creates a 
sequential or direct file. 


A Adds records to an existing indexed or direct file or to the end of 
an existing sequential file. When you use this option, you must also 
specify ADD in columns 16 through 18 of the Output specification. 


U Creates an indexed file and adds records in an unordered sequence. 


For input files, you can choose one of the following entries. 


Entry Explanation 


Blank Reads records from a file without adding new records or changing 
existing records. 


A Reads records from an indexed or direct file and allows you to add 
new records. When you use this option, you must also specify ADD 
in columns 16 through 18 of the Output specification. 
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For update files, you can choose one of the following entries. 


Entry Explanation 
Blank Allows you to update the records in a file. 


A Allows you to update the records in, and add records to, an indexed 
or direct file. When you use this option, you must also specify ADD 
in columns 16 through 18 of the Output specification. 


You cannot add records to an indexed file that is being processed by a 
record-address file. 


15.3.24 Expansion Factor 


When records are added to indexed files, they are placed in buckets. 
(Buckets hold the contents of records.) If you attempt to randomly add a 
record to a full bucket, VAX RMS causes the bucket to split. VAX RMS 
tries to keep half of the records in the original bucket and moves the 
other records to a newly created bucket. Each split record leaves behind 

a pointer to the new bucket. When the system searches for one of the 
records in the newly created bucket, it must first go to the bucket where 
the record previously resided, read the pointer, and then move to the 
bucket indicated by the pointer. This pointer manipulation overhead takes 
time and wastes disk space. 


To prevent bucket splitting and to improve search efficiency, use an 
Expansion factor when creating an indexed file to reserve bucket space for 
the records you write to an indexed file. Also, specify a bucket size that is 
a multiple of the disk cluster size. To show the disk cluster size, type the 
following: 


$ SHOW DEVICE device/FULL 


Use column 67 to specify the expansion factor. 
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Column Allowable 


Number Values Explanation 
67 Blank or 0 Completely fills a bucket 
1 (minimum) Sets indexed bucket fill size to 50% and sets data 
fill size to 100% 
2 (average) Sets indexed bucket fill size to 50% and sets data 
fill size to 75% 
3 (above Sets indexed bucket fill size to 50% and sets data 
average) fill size to 60% — 
4 (maximum) Sets indexed bucket fill size to 50% and sets data 


fill size to 50% 


Additional Information 


If the records you want to add are distributed unevenly by their key 
values, then VAX RMS must split the buckets. In this case, use an expan- 
sion factor of zero. Records with key values that are close in sequence and 
records added to the end of the file cause VAX RMS to split the buckets 
anyway. For these kinds of records, use an expansion factor of zero. 


For output or update indexed files that are being created, VAX RMS uses 
the expansion factor to set the data bucket fill size and indexed bucket fill 
size in the key Extended Attribute Block (XAB). VAX RPG II multiplies the 
bucket size value by 512 and adjusts the result based on the percentages 
listed. 


Table 15-4 shows how the values for expansion factor and block length 
set the values for the following VAX RMS parameters: 

e FAB$B_BKS (bucket size) 

e XAB$W_IFL (indexed bucket fill size) 

e XAB$W_DFL (data bucket fill size) 


See the VAX Record Management Services Reference Manual for information 
on these parameters. See the Guide to VAX/VMS File Applications for 
information on indexed bucket fill size (index—fill) and data bucket fill size 
(data_fill). 
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Table 15-4: Expansion Factor and Block Length Values 


File Block 

Expansion Length FAB$B_BKS XAB$W_IFL XAB$W_DFL 
(minimal) | 1536 3 £44768 1536 | 
2 (average) 2048 4 1024 1536 

3 (above average) 1024 2 512 614 

3 (above average) 2048 4 1024 1228 

4 (maximum) 2000 4 1024 1024 


15.3.25 File Sharing 


Use column 68 to specify the file sharing requirements of the file. File 
sharing allows more than one program to access the records in a file at 
the same time. If more than one program tries to access the same record, 
the first program that accessed the record will be allowed to change it and 
then one of the following options will take effect: 


e¢ S option—the record will be locked, preventing access by other 
programs until the first program is finished with the record 


e R option—the record will be locked, preventing update access by 
other programs, but will not be locked from programs attempting to 


read the record 


However, on a CHAIN operation code, you can specify an indicator to be 
set on when a record is locked, allowing the program to proceed while 
the record is still locked. See Section 16.7.1 for information on CHAIN 
indicators for locked records. 


Column Allowable 


Number Values 
68 Blank 
S 
R 


Explanation 
Uses VAX RMS default file sharing 
Specifies file sharing 


Specifies file sharing with the lock for writing 
option 
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¢ Column 68 must be blank for a display file (D in column 15 of the File 
Description specification) and for an ADDROUT file (Ti in column 32 
of the File Description specification). 


e Specifying S or R in column 68 is valid for a sequential file only if 
the sequential file has fixed-format records (F in column 19 of the File 
Description specification) and with a record length of 512. 


Additional Information 


Table 15-5 shows file sharing that is inherently specified as a result of 
the combination of the entries in columns 15, 66, and 68 of the File 
Description specification. The File Description specification that specifies 
these entries is assumed to be the first to open the file. 


Table 15-5: File Sharing 


Columns 

(b = blank) 
15 66 68 
File ‘File 


Type Addition Share Explanation 


] b b _ Any number of programs with the same 
entries in these three columns can read the file 
simultaneously. Any program with a different 
entry in file type or File Addition for this file 
will receive a file-locked error. 


I A b No other program is allowed simultaneous 

O b,A,U b, access to the file. Any other program will 

U b,A b receive a file-locked error. 

1, b,A,U. S, Any other program with an S or R in Share 
O, R can access the file simultaneously, unless the 
U file is for output and the file does not specify A 


for File Addition, in which case a new version 
of the file is created. Any other program with 
a blank in Share will receive a file-locked error. 


VAX RPG II does not set the SHR field of the File Access Block (FAB) for 
the file when Share is left blank. When you specify S in column 68, 
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VAX RPG II sets the SHR field to allow GET, PUT, DEL, and UPD access. 
When you specify R in column 68, VAX RPG II also sets the RLK option. 
See the Guide to VAX/VMS File Applications for more information on file 
sharing. 


15.3.26 Tape Rewind 


Use column 70 to specify tape rewind that positions a tape according to 
the current conditions. 


Column Allowable 
Number Values Explanation 


70 Blank Indicates either that the file does not reside on tape, 
or, if the file does reside on tape, that the tape will 
rewind when the file is opened and closed 


UorR Rewinds the tape when the file is opened and when 
the file is closed 

N Does not rewind the tape 

K Rewinds the tape when the file is opened 


L Rewinds the tape when the file is closed 


15.3.27 File Condition 


Use columns 71 and 72 to specify the file condition. File condition 
associates an external indicator with a file. External indicators control file 
access at run time. When you condition the file with an external indicator, 
VAX RPG II opens the file only when the external indicator is set on. You 
can use external indicators to condition primary and secondary input and 
update files, record-address files, and output files. You can condition a 
record-address file by using an external indicator only if the following 
conditions are met: 


¢ The record-address file is associated with a primary or secondary input 
or update file. 


e The same indicator (or no indicator) is used to condition the 
associated file. 
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See Chapter 7 for more information on external indicators. 


Column Allowable 


Number Values Explanation 
71,72 Blank Indicates no external indicator for this file 
U1-U8 Names the external indicator that controls file access 
at run time 


When you condition a file with an external indicator, use the same 
indicator to condition calculations and output operations for the 
same file. 


15.3.28 Example 


In the following example: 


Line 1020 describes a primary input file with fixed-record format. 
Each record is 96 bytes long. The file CICWMS resides on disk with a 
symbolic device of XX1. 


Line 1030 describes a demand file for input with fixed-record format. 
Each record is 96 bytes long. The file CARD58 resides on disk with a 
symbolic device of XX2. The external indicator U1 must be set on if 
the file is to be opened. 


Line 1040 describes a demand file for update with fixed-record format. 
Each record is 190 bytes long. The file ICM resides on disk with a 
symbolic device of XX4. 


Line 1110 describes an output file with fixed-length records. Each 
record is 132 bytes long. The output file CONTRL will be written to 
the printer whose symbolic device is X11. The overflow indicator is 
specified to condition output lines when an overflow occurs. 
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Mode (LR) 
IKey length 
Type (IOUDC) || Record address type (APIB) Addtn( AU) 
IDes(PSRCTDF)II lOrganization (IT,1-9) [Expand 
JIEOF (E) 1! [1Overflow indicator Continue (K) [!Shr(SR) 
111Seq (AD) Jl Til Key location Opt = Entry [tl Rewnd 
File PIttFmt (FV) Tt il | Extension (EL) II | Hitt | 
name FINVITIBIK Rec 1} TI! 1 = tDevice Symb Tape Core III IFile 
| Hlttllen len It Til | = tcode dev label index II! Icond 
eee tt Wt | | ttt 4 
) | 4 | 2 | 3) | | 
12345678901234 0 
## TT ee eee ¥ a eH, 
O1020FCICWMS IP F 96 DISK XXi4 
O1030FCARD58 ID F 96 DISK XX2 U4 
01040F ICM UD F 190 DISK XX4 


O1410FCONTRL O F 132 OF PRINTR Xii 
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15.4 Description 


The Extension specification allows you to give VAX RPG II additional 
information about record-address files, tables, and arrays. See Chapter 8 
for information about record-address files. See Chapter 10 for information 
about tables. See Chapter 11 for information about arrays. | 


In general, use the Extension specification to describe the following 
information about a table or array: 

e Name of the table or array 

e Number of entries per record 

e Number of entries per table or array 

e Length of each table entry or array element 

¢ Format of numeric data 

¢ Decimal position 

e Sequence of entries 

e Related tables or related arrays in alternating format 


If your program uses a record-address file, complete columns 11 through 
26 to provide the following information: 


e Name of the record-address file 
e Data file associated with the record-address file 


If your program uses tables or arrays, the time at which you load the 
tables or arrays determines the columns you must complete. For compile- 
time tables and arrays, you must complete columns 19 through 57; for 
preexecution-time tables and arrays, complete columns 11 through 57; and 
for execution-time arrays, complete columns 27 through 32 and columns 
36 through 45. 
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15.4.1 Extension Specification Format 


The format of the Extension specification is as follows: 


ers F = Format (PB) 

| Saeion D = Decimal positions 
il ----S = Sequence (AD) 
It 
l}lAlternating table or array 

From To Table EntEnt LenilIname Len ~ 

file file or perin of FIll of F 

name name array RecTb) EntiDI EntiD 

| | name | | ft IIS! 1 1S 

E I | bo Pt 1 dill | Ill+-- Comments ---+ 
| 2 


ri | 





| 3 | 4 | i) | 6 | 
123456 7890123456 7890123456 7890123456 78901234567890123456789012345678901234567890 
Hove ek % * H-—R---K--KHRE H-— HERE . 
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15.4.2 Specification Type 
Use column 6 to identify the type of specification for every program line. 


Column Allowable 


Number Values Explanation 
6 E Indicates that this program line is an Extension 
specification 


15.4.3 From File Name 


Use columns 11 through 18 to specify the from file name that identi- 
fies the name of the record-address file or the input file used to load a 
preexecution-time table or array. 
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Column Allowable 
Number Values 


11-18 Blank 


Name 


Explanation 


Loads the table or array named in columns 27 
through 32 (table or array name) at compile time, 
if columns 33 through 35 (entry per record) are 
completed. 


Loads the array at execution time if specified by 
the Input and/or Calculation specification and if 
columns 33 through 35 are left blank. 


Names a record-address file, if specified. Otherwise, 
names the table or array input file. VAX RPG II 
uses this file to load the table or array at preexecu- 
tion time. 


¢ This file name must be the same file name you used in the File 
Description specification. 


e Left justify this entry. 


15.4.4 To File Name 


Use columns 19 through 26 to specify the to file name in connection with 
your entry in columns 11 through 18 (from file name). If you name a 
record-address file in columns 11 through 18, specify the name of the 
input or update file it processes in columns 19 through 26. 


Column Allowable 
Number Values 
19-26 Blank 


File name 
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Explanation 


Does not write the table or array file at the end of 
the program. 


Identifies the data file associated with the record- 
address file, if you use a record-address file. If you 
do not use a record-address file, this entry names 
the output file that receives the data from the table 
or array at the end of the program. 


Extension Specification (E) 


This file name must be the same file name you used in ~ File 
Description specification. 


If you want to write a table or an array to an output file at the end of | 
the program, enter the file name in columns 19 through 26. 


You cannot write an execution-time array to an output file. 
Left justify this entry. 


15.4.5 Table or Array Name 


Use columns 27 through 32 to name the table or array you want to use. 


Column Allowable 


Number Values Explanation 
27-32 Blank Indicates that the file named in columns 11 through 


18 (from file name) is a record-address file 
Name Identifies the name of the table or array 


A table name can be any string of three to six alphanumeric characters, 
beginning with TAB. Table names cannot contain embedded blanks. 
An array name can be any string of one to six alphanumeric char- 
acters, beginning with an alphabetic character. Array names cannot 
begin with TAB and cannot contain embedded blanks. 

If you use tables or arrays in alternating format, this entry describes 
the name of the main table or array. Identify the alternate table or 
array name in columns 46 through 51. 


Left justify this entry. 
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15.4.6 Number of Entries in a Record 


Use columns 33 through 35 to specify the number of entries in a 
table or array input record. Complete this entry for compile-time and 
preexecution-time tables and arrays. 


Column Allowable 


Number Values Explanation 
33-35 Blank Indicates a record-address file or an execution-time 
array 
1-999 Specifies the number of entries in a table or array 


input record 


All records except the last must have the same number of entries. The 
last record can have fewer entries to accommodate a number of entries 
that is not an even multiple of the defined number of entries in the 
record. 


The first entry must begin in the first position of the record. 
Leave no spaces between entries in a record. 
Entries cannot span two records. 


If you use tables or arrays in alternating format, each record must 
contain a corresponding entry. The entries from the main table or 
array and the corresponding entries from an alternate table or array 
are treated as one entry. 

Right justify this entry. 

Leading zeros can be omitted. 
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15.4.7. Number of Entries in a Table or Array 
Use columns 36 through 39 to specify the number of entries in a table or 


array and in an alternate table or array, if an alternate table or array is 
used. 


Column Allowable 


Number Values Explanation 
36-39 Blank Indicates that the file named in columns 11 through 


18 (from file name) is a record-address file 


1-9999 Specifies the number of entries in a table or array 


e Ifa compile-time or preexecution-time table or array is not completely 
full, VAX RPG II fills the unused entries with blanks for alphanumeric 
data or zeros for numeric data. If you specify an entry in column 
45 (sequence) of the Extension specification, preexecution-time and 
compile-time tables and arrays must be full (VAX RPG II does not fill 
the short entries). 


e Right justify this entry. 
¢ Leading zeros can be omitted. 


15.4.8 Length of Entry 


Use columns 40 through 42 to specify the length of entry that defines the 
number of character (alphanumeric or numeric) positions in each table or 


array entry. 

Column Allowable 

Number Values Explanation 

40-42 Blank Indicates that the file named in columns 11 through 

2 18 (from file name) is a record-address file 
1-999 Specifies the number of character positions (both 

alphanumeric and numeric) in each table or array 
entry 
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15.4.9 Format 


For an alphanumeric entry, the maximum number of characters is 999. 
For a numeric entry, the maximum number of digits is 15. 

For numeric data, the maximum number of digits in binary format 

is 9. 

For compile-time arrays, the maximum length of an entry is 96 


characters, because this is the largest record that can be entered in the 
source program. 


When you use table and arrays in alternating format, this entry 
specifies the length of the entry in the main table or array. 


Because all entries in a table or array must be the same length, fill 
unused alphanumeric character positions with blanks and fill numeric 
entries with zeros. 


Right justify this entry. 
Leading zeros can be omitted. 


Use column 43 to specify how numeric data is stored. Data can be stored 
in one of the following three formats: 


Overpunched decimal 
Packed decimal 
Binary 


Select a format based on the storage space available and the frequency of 
use. See Chapter 14 for more information on data formats. 
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Column Allowable 
Number . Values 


43 Blank 


15.4.10 Decimal Positions 


Extension Specification (E) 


Explanation 


Specifies that numeric data is in overpunched 
decimal format, or that the table or array contains 
alphanumeric data. If you do not specify a table 
or an array, a blank indicates that the file named 
in columns 11 through 18 (from file name) is a 
record-address file. 


Specifies that numeric data is in packed decimal 
format. This format is valid only for preexecution- 
time tables or arrays. 


Specifies that numeric data is in binary format. This 
format is valid only for preexecution-time tables or 
arrays. 


Use column 44 to specify the number of positions to the right of the 
decimal point for numeric data in a table or array. 


Column Allowable 
Number Values 


44 Blank 


0-9 


Explanation 


Specifies a record-address file or indicates that the 
table or array, if used, contains alphanumeric data 


Specifies the number of positions to the right of the 
decimal point for numeric data in a table or array 


You must specify zero for numeric data with no decimal positions. 


VAX RPG II Specifications 15-57 


Extension Specification (E) 


15.4.11 Sequence 


Use column 45 to specify the sequence that defines the order of entries in 
a table or array. VAX RPG II checks each entry for the order you specify. 


Column Allowable 
Number Values Explanation 


45 


Blank Specifies a record-address file, or indicates that the 
entries in a table or an array are unordered 


A Specifies that the entries in a table or array are in 
ascending order 


D Specifies that the entries in a table or array are in 
descending order 


Consecutive entries that are equal in value are considered to be in 
sequence. 


When you use tables or arrays in alternating format, this entry speci- 
fies the sequence of the main table or array. 


When you specify a sequence for a compile-time or preexecution-time 
table or array, VAX RPG II checks the sequence of the entries in a 
table or an array. If an entry in a compile-time table or array is out 
of sequence, VAX RPG II reports a fatal error during compilation. If a 
preexecution-time table or array is out of sequence, a run-time error 
occurs. 


You must specify a sequence if you use an indicator to test for a HIGH 
or LOW condition in a LOKUP operation associated with the table or 
array. See Chapter 16 for information on LOKUP. 


You can specify a sequence for an execution-time array, but VAX 
RPG II does not check the sequence. However, if the execution-time 
array is not in correct sequence and you specify a LOKUP operation 
with a HIGH or LOW condition, unpredictable results will occur. 


15-58 VAX RPG II Specifications 


Extension Specification (E) 


15.4.12 Alternate Table or Array 


Use columns 46 through 57 to define the name, entry length, data format, 
number of decimal positions, and sequence for an alternate table or array. 
If you specify a table, you must use another table as its alternate. If 

you specify an array, you must use another array as its alternate. The 
same rules for columns 27 through 45 apply to the entries in columns 46 
through 57. 


15.4.13 Comments 


Use columns 58 through 74 to document the program line. 


Column Allowable 


Number Values Explanation 
58-74 Any Documents the program line 
character 


15.4.14 Example 


The following example specifies these operations: 


e A preexecution-time array to be loaded from the file TABLEF at the 
Start of program execution (line 40) 

e A compile-time table with an alternate table (line 50) 

¢ A compile-time array (line 60) 

e An execution-time array (line 70) 
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From To Table 
file file or 
name name array 
| | name 


ae cee: F = Format (PB) 
[ache D = Decimal positions 
I] ----§S = Sequence (AD) 
It : 
l} Alternating table or array 
EntEnt Lenlilname Len 
perin of FIll of F 
RecTb] EntiD!| Ent ID 
1 t ot tS | tis 
Ht 


1 | 1 dll 1 Id]+-- Comments ---+ 


4 | a) | 3) | 7 I 


| i | Q | 3 | 
123456 7890123456 78901234567890123456789012345678901 23456 7890123456 78901254567890 





Miecgiat % % H—-—H-——H-— HERE H-—HKREK 
40E TABLE1 ARRAYi 4 8 50 
5OE TABLE2 4 8 1 TABLES 30 
60E ARRAY2 30 100 1 
70E ARRAYS 30 1 


15-60 VAX RPG Il Specifications 


ZK-4476-85 


Line Counter Specification (L) 


15.5 Description 


The default length for a page of printer output is 66 lines; the default 
overflow line is line 60. When the printer reaches the overflow line, 
VAX RPG II sets the overflow indicator on. 


The Line Counter specification allows you to alter the default page format 
of a printer output file. You can use this specification to change both the 
number of lines on a page and the overflow line. 


15.5.1 Line Counter Specification Format 


The format of the Line Counter specification is as follows: 


Form length (4-112) 
File © | FL (if Form length used) 
name 1 Overflow line number (1-112) 


| 
| | | t OL (Cif Overflow line used) 
LI a 


11 | 
A] | 1 | Q | 3 | 4 | 5 | 3) | 7 | 
123456 7890123456 7830123456 78901234567890123456 7890123456 7890123456 7830123456 7890 


RE H-—* R--% east pueepvpespseeeprespespupeeesesepeeeepepeeseseeseeeseeeeew ees eee ees 
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15.5.2 Specification Type 


Use column 6 to identify the type of specification for every program line. 


Column Allowable 


Number Values Explanation 
6 L Indicates that this program line is a Line Counter 
specification 
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15.5.3 File Name 


Use columns 7 through 14 to name the output file. 


Column Allowable 


Number Values Explanation 
7-14 File name Identifies the name of the output file 
Rules 


¢ The output file must be described on the File Description specification 
with PRINTER in columns 40 through 46 (device code) and L in 
column 39 (extension). 


e Left justify this entry. 


See Chapter 14 for information on naming files. 


15.5.4 Form Length 


Use columns 15 through 17 to define the number of lines printed on a 
page. When the printer reaches the last specified line, it skips to the next 
page and resumes printing. 


Column Allowable 


Number Values Explanation . 
15-17 1-112 Defines the maximum number of lines that can be 


printed on a page 


¢ This entry must be a numeric value. 
e Right justify this entry. 
e Leading zeros can be omitted. 
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If you specify an entry in columns 15 through 17 (form length), you must 
enter FL in columns 18 and 19. This entry specifies that columns 15 
through 17 define the form length. 


Column Allowable 


Number Values Explanation 
18,19 FL , Causes VAX RPG II to use the form length defined 


in columns 15 through 17 


15.5.6 Overflow Line Number 


Use columns 20 through 22 to specify the overflow line number. When 
the page reaches the overflow line, VAX RPG II sets the overflow indicator 
on. 


Column Allowable 


Number Values Explanation . 
20-22 1-112 Specifies the overflow line number 
Rules 


e This entry must be equal to or less than the entry in columns 15 
through 17 (form length). 


¢ This entry must be a numeric value. 
e §=Right justify this entry. 
e Leading zeros can be omitted. 
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15.5.7. OL 


If you specify an overflow line number in columns 20 through 22 (over- 
flow line number), you must enter OL in columns 23 and 24. This entry 
specifies that columns 20 through 22 define the overflow line number. 


Column Allowable 
Number Values Explanation 


23,24 OL Causes VAX RPG II to use the overflow line number 
defined in columns 20 through 22. 


In the following example, the form length is 100 lines and the overflow 
line number is line 96: 


Form length (1-112) 
File 1 FL (if Form length used) 
name | Overflow line number (1-412) 


| 
| 1 |} OL Cif Overflow line used) 
1 tlt . 


LI 





Ht | 2 | 3 I 4 | | Ls) | ¢ | 
1234567890123456789012345678901234567890123456 7890123456789012345678901234567890 
R¥ H--k 4-—% 
LINPUT  i100FL 960L 
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15.6 Description 


The Input specification describes the records in input and update files. 
Each record is further divided into fields. Columns 7 through 42 describe 
the file and its records. Columns 43 through 74 describe the fields in each 
record. 


The Input specification also describes data structure statements and data 
structure subfields. See Section 15.6.4 for information on data structures. 


You must use an Input specification to describe each input or update file 
except for table input files and record-address files. 


15.6.1 Input Specification Format 


The format of the Input specification is as follows: 


Sequence (AA-ZZ, 01-99) 
| Number (4-N) 


| 10ptional/External (OU) Decimal positions 
| |lRecord identifying indicator | Control level 
1 ll | | Match field 
1 (ll + Identifying codes + Format | | | Fld rec rel 
File Pt 1 | (PB) IField | JI I 
name. I Til | : C Cl IField tIname | | | Field 
| fit : Z Z| llocation! | 1 1 pettanhs 
1 it | | i+ 


Pos cee NDcPos NDc IFr To II 





| 1 | 2 | 3 | 4 I 5 | 6 | 7 | 

123456 7890123456 78901234567890123456 7890123456 7890123456 7890123456 78901234567890 
He % HK X-—-- #--- ¥--- 2 R¥-—-—K—-—-—- HF Ree HK Lae 
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15.6.2 Specification Type 


Use column 6 to identify the type of specification for every program line. 
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Column Allowable 


Number Values Explanation . 
6 I Indicates that this program line is an Input specifi- 
cation 


15.6.3 File Name 


Use columns 7 through 14 to name the input or update file. 


Column Allowable 


Number Values Explanation . 
7-14 File name Identifies the name of the input or update file 
Rules 


Use the same name you specified in the File Description specification. 


If this column is blank, VAX RPG II assumes that the information in 
this program line describes a field or record from the file named last. 


Describe all the records and fields for one file before describing 
another file. 


Left justify this entry. 
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In the following example, EMPLOYEE is the name of the input file, and 
the fields NAME and ADDRES, each containing 20 characters, belong to 
each record in the file: 


Sequence (AA-ZZ, 01-99) 
} Number (1-N) 





| lOptional/External (QU) Decimal positions 
| {lRecord identifying indicator | Control level 
1 ttl me | | Match field 
| Ill + Identifying codes + Format | | | Fld rec rel 
File 1 uit | | (PB). IField | 1 I 
name util ¢C C Cl IField Iname | 1 | Field 
| Litt tb Z Z Z| location! | 1 1 | indicatrs 
Il 1-114 Pos NDcPos NDcPos NDc IFr. To II l-l}+-9 
0 | 
ee eT HH HEH HK wae 
IEMPLOYEEAA 
I 4 20 NAME 
I 21 44 ADDRES 
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15.6.4 Data Structures 


Data structures consist of a data structure statement and zero or more 
data structure subfields. You must describe data structures on Input 
specifications. Data structures follow all Input specifications (including all 
modifier specifications) for records. 


You can use data structures to do the following: 


e Define one area of storage more than one way 

e Define subfields within a field or subfield 

e Reorganize fields in an input record 

e Select the internal numeric data type for fields 

¢ Communicate information between programs with a local data area 
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15.6.4.1 Data Structure Statement 
The format of the data structure statement is as follows: 


Column Allowable 


Number Values Explanation 
7-12 Data Identifies the data structure. The data structure 
structure name, which is not required, can be a field defined 
name on Input specifications or Calculation specifications 
__ or defined nowhere else in the program. 
18 U Optional. Identifies this data structure as the local 
data area. 
19-20 DS Specifies a data structure. 
48-51 1-9999 Columns 48 through 51 may optionally contain the 
data structure length. 
Rules 


The data structure name can appear on only one data structure 
specification, cannot be a look-ahead field, and can be specified 
anywhere a character field is allowed. | 


The length of the data structure is one of the following: 


— The length specified in the Input specification, if the data structure 
name is an input field 


— The length specified in columns 48 through 51 of the data struc- 
ture statement 


— The highest to position (end position) of a subfield within a data 
structure, if the data structure name is not an input field 


The length computed by the to position must be less than or equal 
to the length specified in the Input specification or the data structure 
statement. 


Any length on a Calculation specification must match the largest value 
specified in the Input specification or the data structure statement. 


Because it is possible to specify the length of a single data structure in 
all of the preceding ways in a single VAX RPG II program, a compiler 
diagnostic will be given for any conflicts. This will not occur if the 
length in columns 48 through 51 exceeds the highest to position for 
any subfield in the data structure. 
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15.6.4.2 Data Structure Subfields 


Data structure subfields are specified in columns 43 through 58. They 
are defined the same as for any other input field specification. See 
Sections 15.6.11 through 15.6.14 for those field specification requirements. 


The field location’s start and end positions are relative to the beginning of 
the data structure, not to the beginning of the data record. 


All columns except columns 43 through 58 must be left blank. 


The subfield name can be the same as a field defined on an Input 
specification or a Calculation specification. 


Subfields can be used as factor 1, factor 2, or the result field of a 
Calculation specification or as output fields. 


The same subfield name cannot be used in more than one data 
structure. 


A data structure name cannot be used as a subfield name in another 
data structure. 


Numeric subfields must contain numeric data when used in CHAIN, 
LOKUP, COMP, editing, or arithmetic operations. 


If arrays are specified as subfields, the length specified must equal the 
amount of storage required to store the entire array. 


A data structure subfield cannot be an indicator (*IN field) or a UDATE 
field. 


Overlapping subfields cannot be used in the same calculation in such 
a way that the result field overlaps either factor 1 or factor 2. If either 
factor 1, factor 2, or the result field references a subfield in a data 
structure that is an entire array or an array with a variable index, 
then that array is used to determine whether overlap exists. The 
same array name can be referenced in the appropriate factors of a 
Calculation specification without violating the overlap rule. 


Any subfield previously defined in an input record must be the same 

in length (in digits) and in decimal positions. If the numeric data type 
is different from what was specified in an input record, the length (in 

digits) must still be the same as previously defined. 


Any subfield defined more than once in the same data structure 
must be defined with the same data type and start position, the same 
length, and the same decimal positions, in the data structure. 
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e Neither data structures nor data structure subfields can be individual 
array elements. 


e = All entries for a data structure statement and its data structure sub- 
fields must appear together; they cannot be mixed with entries for 
other data structures. 


e A data structure statement and a data structure subfield cannot have 
the same name. 


See Section 15.6.15 for examples of using data structures. 


15.6.4.3 Local Data Area 


The VAX RPG II local data area is a data structure of up to 512 bytes used 
to communicate information from one VAX RPG II program to another. 

In addition, the VAX RPG II local data area can be manipulated (read or 
written) at DCL command level or from a program written in another 


language. 


To specify a local data area, a data structure must have a U in column 
18 on the Input specifications. The data structure does not need a name. 
Only the first 512 bytes of the data structure are loaded at program start 
and written at program exit. Only one data structure may have a U 
specified in column 18. 


The VAX RPG II local data area is implemented with VAX/VMS DCL 
symbols (see the VAX/VMS DCL Dictionary for examples of manipulating 
DCL symbols). The following four symbols correspond to the indicated 
bytes within a data structure which has a U specified in column 18: 


RPG$LDA1 1-128 

RPG$LDA2 129-256 
RPG$LDA3 257-384 
RPG$LDA4 385-512 
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Use columns 15 and 16 to specify the sequence that defines the ordering 
sequence of the record types in a file (for example, distinguishing em- 
ployee name records from employee badge number records). VAX RPG 
II does not order records according to sequence; it checks the sequence of 
records in the input or update file instead. 


Column Allowable 


Number Values Explanation 

15,16 Any two Performs no sequence checking for this record. 
alphabetic You can use any two letters from AA through ZZ, 
characters for example, BB, ZA, or DE. You must specify an 


alphabetic sequence for chained and demand files 
and look-ahead fields. 


Blanks Specifies no sequence checking for this record. 
Any Assigns a sequence number to a record. You can 
two-digit use any two numbers from 01 to 99; however, 
number you must use sequence codes in ascending order, 


beginning with 01. 


VAX RPG II does not require that all Input specifications in alphabetic 
sequence appear before those Input specifications in numeric sequence. 


15.6.6 Number 


If you assigned a numeric sequence code in columns 15 and 16, use 
column 17 to indicate the number of records in a record type. 


Column Allowable 


Number Values Explanation 
17 1 Specifies that there is only one record of this type 
N Specifies that there can be more than one record of 
this type 


Leave this column blank if you specified an alphabetic sequence in 
columns 15 and 16. 
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15.6.7 Option 


If you assigned a numeric sequence code in columns 15 and 16, you can 
use column 18 to specify whether a record of that type must be present to 
continue processing records. 


Column Allowable 


Number Values Explanation 
18 Blank Specifies that a record of that type must be present 
O Specifies that a record of that type is optional 


Leave this column blank, if you specified an alphabetic sequence in 
columns 15 and 16. 


15.6.8 Record-Identifying Indicator 


Specifying an indicator in columns 19 and 20 associates the indicator with 
a particular record type. When VAX RPG II processes a record of the 
type you specify for this program line, it also sets on the indicator, which 
remains on until after detail-time output. Then, VAX RPG II sets off all 
indicators used as record-identifying indicators. See Chapter 7 for more 
information. 


Column Allowable 


Number Values Explanation 
19,20 Blank Specifies not to set on an indicator when VAX RPG 
II processes a record of the type you specify. 
01-99 Specifies a record-identifying indicator. 
L1-L9 Specifies a control-level indicator. When VAX 


RPG II sets on this type of indicator, it does not 
automatically set on lower-level control-level 


indicators. 
H1-H9 Specifies a halt indicator. 
LR Specifies a last-record indicator. 
** Specifies that the fields described on the subsequent. 


program lines are look-ahead fields. 


DS Specifies a data structure. 
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Look-ahead fields allow you to do the following: 


¢ Determine when the last record of a control group is processed 
e Extend the matching-field processing capability 


VAX RPG II typically processes one record at a time. The data from the 
record currently being processed is available. With look-ahead fields, 
you can evaluate the data from the next record to be processed and then 
determine which operation to perform. 


Any or all of the fields in a file can be specified as look-ahead fields. The 
description applies to all records regardless of their record type. 


To specify a field as a look-ahead field, you must enter a double asterisk 
(**) in columns 19 and 20 of the Input specification. Also, you must spec- 
ify an alphabetic sequence in columns 15 and 16 of the Input specification. 
All other columns must be blank. Then, on the next program line, enter 
the field name, as shown in the following example: 


Sequence (AA-ZZ, 01-99) 
| Number (1-N) 





| lOptional/External (OU) Decimal positions 
| |tRecord identifying indicator | Control level 
1 tlt | | Match field 
1 Ill + Identifying codes + Format | | | Fld rec rel 
File r tll | | | (PB) IField I | | 
name 1 dtl ¢ ¢C Cl IField tname | 1 | Field 
| 1 tlt Z Z Z! llocation! | | | | indicatrs 
II | |1l Pos NDcPos NDcPos NDc IFr To II 1} i 1+-0 
4 2 | 3 | 4 5 6 | 
123456 7890123456 78901234567890123456 7890123456 7890123456 789012345678901234567890 
x% A ne nn nee, ee eee T HERR HR vee 
IEMPLOYEEAA 014 
I {1 20 NAME 
I BB 
I 21 25 BADGE 
ZK-448 1-85 
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@  Look-ahead fields can be used only with input or eae primary or 
secondary files. 


e For input files, look-ahead fields apply to the next record in the file. 


e For update files, look-ahead fields apply only to the next record in the 
file if the current record being processed was read from another file. 
Therefore, if you are using only one file, the look-ahead field is the 
current record being processed. 


e Look-ahead fields can be specified only once in a file. 
¢ Look-ahead fields cannot be the only record in the file. 


e As VAX RPG II processes the last record, it fills any look-ahead fields 
with 9s. In this case, if the field is 10 characters long, it will contain 
the data 9999999999, ) 


e Columns 59 through 70 must be blank on Input specifications describ- 
ing look-ahead fields. © 


e You cannot specify blank after (B in column 39 of the Output specifi- 
cation) for look-ahead fields. 


e A look-ahead field cannot be used as a result field in a . Calculation 
specification. 


15.6.9 Record Identification Codes 


Use columns 21 through 41 to define a record type and to specify the code 
that indicates how to identify it. You can subdivide these columns into 
three subsets (columns 21 through 27, 28 through 34, and 35 through 41), 
each defining a different code. 


If you use more than one subset, the record must satisfy all record identi- 
fication codes. Used in this way, the codes form an AND relationship. If 
VAX RPG II cannot identify a record according to the identification codes 
of all the records in a file, it issues a run-time error. 


If there is only one record type for a file, you can leave these columns 
blank. Also, you can leave these columns blank when describing the last 
record type in a file. This defines a record type to catch all records that do 
not fall into any of the record types you previously described. 


VAX RPG II checks records for a record type in the order in which you 
specify them on the Input specification. 
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15.6.9.1 Position 


Use columns 21 through 24, 28 through 31, and 35 through 38 to define 
the position that specifies where to look for the identification code in the 
input record. 


Column Allowable 


Number Values Explanation 

21-24 Blank Indicates that there is no record identification code. 
28-31 In this case, make sure that the corresponding not, 
35-38 character (C), zone (Z), or digit (D) portion and the 


character columns are blank. 


1-9999 Defines the position of the character you specify in 
columns 27, 34, and 41. For example, the number 
in columns 28 through 31 specifies the position of 
the character in column 34. _ 


Rules 
e = Right justify this entry. 
° Leading zeros can be omitted. 


15.6.9.2 Not 


Use columns 25, 32, and 39 to specify whether an identification code must 
be present in the input record. 


Column Allowable 


Number Values Explanation 
25,32,39 Blank . Indicates that the identification code you specify 


in the next two columns (26 and 27, 33 and 34, 
and 40 and 41) must be present to identify a record 
type. For example, if column 32 is left blank, the 
identification code in columns 33 and 34 must be 
present. | 


N Indicates that the identification code must not be 
present to identify a record type. For example, if 
you specify N in column 339, the identification code 
in columns 40 and 41 must not be present. 
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15.6.9.3  CZD Portion 


Use columns 26, 33, and 40 to specify what portion of the character to use 
when identifying a record code. You can use the character (C), zone (Z), 
or digit (D) portion of the character. Many characters have either the same 
zone or digit portion. To distinguish between zone and digit portions, 
you must use their EBCDIC equivalent. See Appendix A for the ASCII 
character set and their corresponding EBCDIC zone and digit codes. 


Column Allowable 
Number Values Explanation 


26,33,40 Blank Indicates that there is no record identification 
code. Its corresponding position, not, and character 
columns must be left blank. 


Cc Causes VAX RPG II to use the entire character to 
identify the record. 

Z Causes VAX RPG II to use the EBCDIC zone 
portion to identify the record. 

D Causes VAX RPG II to use the EBCDIC digit portion 


to identify the record. 


15.6.9.4 Character 


Use columns 27, 34, and 41 to specify the identification character for the 
input record. | 


Column Allowable 


Number Values Explanation 
27,34,41 Any Specifies the character part of the identification code 
character 


In the following example: 


e lin column 6 specifies that this program line is an Input specification. 


e EMPLOYEE in columns 7 through 14 names the input file. This file 
contains the name, address, and telephone number for each employee. 


e The characters AA in columns 15 and 16 specify no sequence 
checking. 
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e VAX RPG II sets on the indicator you specified in columns 19 and 20 
(05) after it reads a record that matches the identification code defined 
in columns 21 through 41. 


There are three parts to the code that identifies this record type: 
1. Position 1 must contain the character A. 
2. Position 31 must contain the character C. 


3. Position 123 must not contain a character with an EBCDIC digit 
portion of the number 6. This includes the characters F, O, W, 6, 
f, o, and w. 


Sequence (AA-ZZ, 01-99) 

| Number (1-N) 

| lOptional/External (OU) Decimal positions 
Record identifying indicator | Control level 
I Match field 


I tl 
1 tl 
| Ill + Identifying codes + Format | | | Fld rec rel 
File ruth | | (PB) Field | I | 
name 1 uliot C ¢C Cl IField Iname | | | Field 
| Pit | Z Z Z| |location| | | | t indicatrs 
I] | 11! Pos NDcPos NDcPos NDc IFr To II fi |+t-9 





i 3 | 4 | 5 | 5) | 7 | 
123456 7890123456 7890123456789012345678901234567890123456 7890123456 78901234567890 
HX H RRE R--- kee= EK RR—--—-H-—-- KK ENR RE ea 


IEMPLOYEEAA 05 1 CA 34 CC 123ND6. 
ZK-4482-85 


15.6.10 AND and OR 


Entering AND in columns 14 through 16 or entering OR in columns 14 
and 15 associates two program lines that specify an identification code. 


AND specifies that the identification codes in two program lines must be 
matched in order to identify the record and to set on the record-identifying 
indicator, if one is specified. 


OR specifies that the identification code in either program line must be 
matched in order to identify the record and to set on the record-identifying 
indicator, if one is specified. 
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Column Allowable 
Number Values Explanation 


14-16 AND Specifies an AND relationship between the identifi- 
. cation codes on this program line and the previous 
program line 


14,15 OR Specifies an OR relationship between the record 
identification codes on this program line and the 
previous program line 


Rules 
e If you use AND, columns 7 through 13 and 17 through 20 must be 
left blank. 
_@ Tf you use OR, columns 7 through 13 and 16 through 18 must be left 
blank. 


¢ You can enter a record-identifying indicator in columns 19 and 20 
in an OR line. If you leave columns 19 and 20 blank, the record- 
identifying indicator in the preceding program line also applies to this 
program line. 


In the following example, there are four characters that identify a record 
type in the file EMPLOYEE: 

1. Position 1 must contain the character A. 

2. Position 31 must contain the character C. 

3. Position 1111 must contain the character zero. 

4. Position 123 must not contain the digit 6. 


The record must meet all the conditions in both program lines before 
VAX RPG II sets on the indicator (05). 


VAX RPG II identifies a record type in the file RETIRED if position 1 
contains the character I and position 31 contains the character D, or if 
position 123 does not contain the digit 6. The record must meet the 
conditions defined in either program line before VAX RPG II sets on the 
indicator (06). 
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Sequence (AA-ZZ, 01-99) 
| Number (1-N) 








| lOptional/External (OU) Decimal positions 
| |lRecord identifying indicator | Control level 
1 til | | Match field 
| Ill + Identifying codes + Format | | | Fld rec rel 
File 1 uth | | | (PB) JField | J I 
name 1 itt ¢ C Cl IField tname | | | Field 
| 1 ult Z Z ZI llocation! | | ! | indicatrs 
|_|}! Pos NDcPos NDcPos NDc IFr_ To Il || |+- 0 
{ | 2 I 3 | ry 5 | 6 | q | 
123456 78901234567890123456 7890123456 7890123456 7890123456789012345678901234567890 





#% Pe a nn eS oer ee Ty ERK HE, 
IEMPLOYEEAA 05 14 CA 34 CC 123NC6 

I AND 4111 Co 

IRETIRED AA 06 1 CI 31 CD 

I OR 123NC6 


ZK-4483-85 


15.6.11 Format 


Use columns 7 through 41 to describe the file and the records in the file. 
Use columns 43 through 75 to describe the fields of each record. Field 
descriptions must begin one line below the file and record description. 
Use a separate line to describe each field you plan to use. 


If a field contains numeric data, use column 43 to specify its format. You 
can specify overpunched decimal, packed decimal, or binary format. See 
Chapter 14 for information on data formats. 


Column Allowable 


Number Values Explanation 
43 Blank Indicates that the field contains either alphanumeric 
characters or numeric data in overpunched decimal 
format 
y Indicates that numeric data is in packed decimal 
format 
B Indicates that numeric data is in binary format 


See Chapter 14 for information on numeric data types. 
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15.6.12 Field Lecations From and To 


You define the fields of a record by specifying their location. Use columns 
44 through 47 to specify the beginning character position of the field. Use 
columns 48 through 51 to specify the ending character position of the 
field. 


Column Allowable 


Number Values Explanation 

44-47 1-9999 Specifies the beginning character position of the 
field 

48-51 1-9999 Specifies the ending character position of the field 

Rules 


The maximum length of a field depends on the type of data it con- 
tains. The maximum field length of overpunched decimal data is 15. 
The field length of binary data can be 2 or 4. The maximum field 
length of packed decimal data is 8. To determine the field length 
of packed decimal data, divide the number of digits by 2 and add 
1, ignoring the remainder. For example, if the number of digits in 
packed decimal data is 9, the length is 5. The maximum field length 
of alphanumeric data is 9999. 


Fields can overlap if you give each field a different name. 
Right justify this entry. 
Leading zeros can be omitted. 
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If a field contains numeric data, use column 52 to specify the number of 
digits to the right of the decimal point. 


Column 
Number 


52 


Allowable 
Values 


Blank 
0-9 


Explanation 
Indicates that this field contains alphanumeric data 


Specifies the number of positions to the right of the 
decimal point 


e You must specify a value in this column even if the numeric data has 
no decimal points. In this case, use zero. 


¢ The number of decimal positions must be less than or equal to the 
number of digits in the numeric field. 


If you specify 2 in this column and the field contains the data 12345, the 
field’s value is interpreted as 123.45. If you specify 4 in this column and 
the field contains the data 12345, the field’s value is interpreted as 1.2345. 


15.6.14 Field Name 


Use columns 53 through 58 to assign a name to the field you defined in 
columns 43 through 52, or to specify the page number for PAGE. 


Column 
Number 


53-58 


Allowable 
Values 


Name 


PAGE 
PAGE1-PAGE7 


*IN,*INxx 


Explanation 


Specifies the name of the field. The name can be a 
field name, array name, or array element. 


Specifies a page number. See Chapter 9 for more 
information on paging special words. 


Sets the specified indicator. See Chapter 7 for more 
information on indicators. 
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¢ The field name can be any combination of six characters except for 
blanks or special characters, as long as the first character is a letter. 
See Chapter 14 for more information on user-defined names. 


e You cannot use the reserved words UDATE, UDAY, UMONTH, and 


UYEAR as a field name. 


e Use a unique name for each field. If you use the same name to 
describe more than one field in the same record type, VAX RPG II 


uses the field described last. 


¢ You can use the same name for fields of different record types as long 
as both fields are numeric with the same number of digits, or both 
fields are alphanumeric with the same length. 


e You can load an entire array from an input record by entering the 
array name in columns 53 through 58. If you do, columns 59 through 


62 and 65 through 70 must be blank. 


e You can load an array element by entering the array name followed 


by a comma and an array index. 


To eliminate duplicate coding, use OR in columns 15 and 16 to define 
the same field names for different record types, as shown in the following 


example: 


Sequence (AA-ZZ, 01-99) 

| Number (1-N) 

| !Optional/External (OU) 

Record identifying indicator 


1 tl 
1 tt 
1 It 
File tl 
ttl 
Il 
me 


| 

| + Identifying codes + Format 

1 | | | (PB) 
name 1 | ¢C ¢ Cl IField 
| 7 | Z Z Z| llocation| | 


I| 






Pos NDcPos NDcPos NDc IFr. To 
0 | 1 | 2 | 3 | 4 | 5 
123456 7890123456 7890123456 7890123456 789012345678901234567 


Decimal positions 
| Control level 
| | Match field 


| | | Fld rec rel 
I\Field | I | 
Iname | | { Field 

| : : indicatrs 


lI a 
| 


6 7 
345678901234567890 
x *% ¥ 





Pr) ee ee ae 
IEMPLOYEEAA 05 1 CA 

I OR 06 51 D6 

I 4 30 NAME 

I 31 50 ADDRES 

I 5i 600PHONE 
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In this example, there are the same three fields (NAME, ADDRES, and 
PHONE) in two different types of records. In the first record type, the 
character A is in position 1. In the second record type, the number 6 is in 
position 51. 


The NAME field contains alphanumeric data; it begins in position 1 and 
ends in position 30. The ADDRES field contains alphanumeric data; it 
begins in position 31 and ends in position 50. The PHONE field contains 
numeric data with no decimal positions; it begins in position 51 and ends 
in position 60. 


15.6.15 Examples of Using Data Structures 


This section provides examples of using data structures in a VAX RPG II 
program. 


15.6.15.1 Multiple Definitions of Storage Area 


The following example shows two fields that would normally require 1550 
and 2400 bytes of storage without data structures. With data structures, 
however, these two fields are allocated using the same 2400 bytes of 
storage. In addition, several subfields within these fields are defined. The 
byte locations for each data structure subfield identify the locations, in a 
single data structure, where each data structure subfield is allocated. 


This example also demonstrates the optional length specification of 
the data structure on the data structure statement. If you omit the 
length of the data structure, VAX RPG II computes it as described in 
Section 15.6.4.1. 
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Sequence (AA-ZZ, 01-99) 

| Number (1-N) 

| lOptional/External (OU) 

Record identifying indicator 


1 tl 
1 ill 
| Il + Identifying codes + Format 
File | 1 | (PB) 
name 1 utl C C Cl IlField 
| 1 ull Z Z ZI llocation 
I| 1 f11 Pos NDcPos NDcPos NDc IFr To 
iT | 2 i 3 | 4 | 
1234567890123456 7890123456 7890123456 7890123456 78901 





%% 
IPERSNELL 


I 
IMEDICAL 
I 


% RH H--- 
O1 


02 


¥---  ¥--- 


11550 


12400 
I DS 2400 
IXPERSONNEL RECORDS FIELDS 

11550 

{ 50 
50 100 
100 150 
150 800 
8001500 


12400 
1 550 
550 950 
9501550 
15501950 
19502400 


*MEDICAL RECORDS FIELDS 


SSeS See eS Set ee ee 


15.6.15.2 Defining Subfields Within a Field or 


Decimal positions 
| Control level 
| | Match field 
| 1 | Fld rec rel 
iField | | | 
Iname | | | Field 
| | | | indicatrs 
lI 1; ti )+-0 
5 


2345678 


BEGRND 
FTRUSE 


MREC 
IMNLGY 
HMTLGY 
RADLGY 
XRAY 
OPROOM 
ZK-4485-85 


Subfield 


The following example shows how to divide a field into subfields. To do 
this, you must specify the name of the field to be divided on the Input 


specification data structure statement. 


15-84 VAX RPG II Specifications 


Input Specification (I) 





0 I i | 2 | 3 | 4 5 I 6 I 7? | 
1234567890123456 78901 2345678901 2345678901234567890123456789012545678901234567890 
#¥ % REE ¥--- #--- ¥--- 2 R¥-——¥——KE RRR HE aee 

ISURPLUS 04 

I 1 12 ITEM 

IITEM DS 

I 4 4 WHOSER 

I 5 8 AREAH 

I 9 12 YEAR 

I 41 11 DECADE. 


ZK-4486-85 


15.6.15.3 Reorganizing Fields in an Input Record 


In the following example, a data structure is used to reorganize fields 
from an input record. The first collection of fields describes the input 
record field layout. The second collection of fields (in the data structure) 
describes how the fields are organized in memory when the program runs. 


Vi gh wed ce et Bee a tenes oe ey. Ra Ab Bye cocks gag Al 





1234567890123456 7890123456 7890123456 78901234567890123456 7890123456 78901234567890 
% H RHE X--- #--- --- 2 ¥R—-—-—k—-~-—- KE RENE RH ua, 


IPART AA 





1 3 °PN 
4 10 PNANE 
14 12 WHOUSE 
13 20 COLWEI 
13 17 COLOR 
18 20 WEIGHT 
19 200NWEIGH 

21 24 QTY 


19 21 PN 
4 10 PNAME 
41 17 WHOCOL 
11 12 WHOUSE 
13 17 COLOR 
4 3 WEIGHT 
23 26 QTY 


REGROP DS 


et tn et et tt Sst st st 


Z2K-4487-85 
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This example shows the difference between an input field (the PART 
record) and a data structure subfield (the REGROP data structure). If either 
of the fields COLOR or WEIGHT is changed in a Calculation specification, 
no change will be reflected in the field COLWEI because COLOR and 
WEIGHT are not redefinitions of that field. In contrast, if either COLOR 
or WHOUSE is changed, WHOCOL will also change because COLOR is a 
redefinition of one portion of that field, and WHOUSE is a redefinition of 
another portion of that field. Changing WHOCOL changes COLOR and 
WHOUSE. Changing the value of COLWEI in a Calculation specification 
will not change COLOR or WEIGHT. 


15.6.15.4 Selecting the Internal Numeric Data Type for Fields 


The following example shows how to use a data structure to select a 
numeric data type that will be used internally. Choosing specific numeric 
data types can improve performance where numeric fields are passed as 
parameters in a CALL statement, because numeric data type conversion 
is then not needed at run time. In this example, the numeric data type is 
indicated by the field name. 





W) | 1 | 2 | 3 | 4 | a) | 6 | ri | 
123456 789012345678901234567890123456 7890123456 7890123456789012345678901234567890 
H RRR H--- ¥--- ¥--- o REM K-— HK a 2 
DS 
P 4 3S0OPACKED 
B 4 SOWORD 
B 6 90LONGWO 
10 1400VERPU 


ZK-4488-85 


If you specify a numeric data type for a data structure subfield, VAX RPG 
II does not automatically convert numerics to packed decimal format. A 
numeric conversion is performed if you define a subfield with a numeric 
data type that is different from the input field declaration. Arithmetic com- - 
parisons are done with the field maintaining the declared data type. Note 
that arithmetic operations (ADD/ SUB/ MULT/DIV) are still performed in 
packed decimal format, and a conversion is made before performing any 
of the arithmetic operations. 


Where VAX/VMS Run-Time Library routines are called with various 
numeric data types, you can use data structures to declare the numeric 
data type so a conversion is not needed for the CALL statement. 


Note that data structures do not support floating point numeric data. 
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The following example shows several numeric fields defined in an input 
record, then redefined with different numeric data types in a data struc- 
ture. Each field redefinition must have the same number of digits as any 
previous field definition. 


| 3 l 4 | 5 | 6 z 


| | 7 | 
123456789012345678901234567890123456 7890123456 7890123456789012345678901234567890 





%% 
IFILE 


de ee est Ss st et est st st 


% HER E-—-W- ¥--- #--- AS tote Soteetet 5.3 a a 
BB 
B 1  20IWORD4 
B 11 440ILONC9 
P 24 250IPACK9 
31 3401 0VER4 
41 4701 0VER7 
51 S90I0VER9 
Ds 
1  40IWORD4 
11 450ILONG9 
24 240IPACKY 
31 32010VER4 
44 440I0VER7 
51 S401 0VER9 


f+ = ins = = = ee] 
ol 
— 


ZK-4489-85 


Each field is named to highlight the number of digits assigned to it, as 
defined in the input record. For example, PACK9 is defined to be a 5-byte 
(9-digit) field in the input record. The data structure indicates that PACK9 
will be stored internally in the data structure as a longword (4 bytes). 
OVER7 is defined to be a 7-byte (7-digit) field in the input record. The 
data structure indicates that OVER7 will be stored internally in the data 
structure as a packed field (4 bytes). In all cases, the number of digits for 
the field as defined on the input record must be the same as the number | 
of digits in any subsequent field redefinition. 
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15.6.15.5 Examples of Using Local Data Area 


The following example demonstrates use of a local data area. The program 
LDA is as follows: 





1) ] 4 | F: | 3 | 4 | 5 lO Ls) | 7 | 
123456 7890125456 78901234567890123456 7890123456 7890125456 7890123456 7890123456 7890 





FITY D OY 80 TTY 

I UDS 

I 4 15 NAME 
I 16 170AGE 
C NANE DSPLYTTY 

C AGE DSPLYTTY 

C MOVEL’S. Jones’NAME 

C Z-ADD29 AGE 

C SETON LR 
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The following commands load the local data area with a name and age. 
The name and age are modified in the program, and this information is 
written back to the local data area upon exiting the program. 


$¢ RPG$LDA1 = "K. Smith ‘ 
$ RPG$LDA1[15,2] := "45" 

$ RUN LDA 

K. Smith 

45 

¢ SHOW SYMBOL RPG$LDA1 
RPG$LDA1 = "S. Jones 29" 
¢ RUN LDA 

S. Jones 

29 
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The following example demonstrates use of a local data area which 
contains binary data. The program LDA_BINARY is as follows: 


i] | 1 | 2 | 3 | 4 | a) | 6 | 7 
1234567890123456789012345678901234567890123456 7890123456 789012345678901234567890 





FTITY D6 CY 80 TTY 

I UDS 

I 4 15 NAME 
I B 16 470AGE 
C NAME DSPLYTTY 

C AGE DSPLYTTY 

C MOVEL’S. Jones ’NAME 

C Z-ADD29 AGE 

C SETON LR 
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The following commands load the local data area with a name and age. 
The name and age are modified in the program, and this information is 
written back to the local data area upon exiting the program. 


$ RPG$LDA1 = "K. Smith " 
$ RPG$LDA1[15*8,16] = 45 

$ RUN LDA_BINARY 

K. Smith 

45 

$ RUN LDA_BINARY 

S. Jones 

29 


The following example demonstrates use of a local data area with 386 
bytes of information. The program LDA_386 is as follows: 










0 | i | ro | 3 | 4 | 5 | Aci 
1234567890123456789012345678901234567890123456 78901234567890123456 7890125456 7890 





IDS386 UDS 

I i 383 DATA 
I 384 386 DATA2 
¢ MOVE ‘abe’ DATAe 

C SETON LR 
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The following commands display the information written to the local data 
area by the program: 


$ RUN LDA_386 

$ CHAR_384 = FS$EXTRACT(127,1,RPG$LDA3) 
$ SHOW SYMBOL CHAR_384 

CHAR_384 = "a" 

$ SHOW SYMBOL RPG$LDA4 

RPG$LDA4 = "bc" 


Note that in this example, the field DATA1 overlaps RPG$LDA1, 
RPG$LDA2, and RPG$LDA3. The field DATA2 is written to the last 
byte of RPG$LDA3 and the first two bytes of RPG$LDA4. 


15.6.16 Control-Level Indicator 


Use columns 59 and 60 to specify control-level indicators. Control-level 
indicators cause VAX RPG II to compare the contents of a field with the 
contents of the same field from a previous record. If the fields are not 
equal, a control break occurs and VAX RPG II sets on the control-level 
indicator assigned to that field. 


You can use this type of indicator to condition input, calculation, and 
output operations. 


Column Allowable 


Number Values Explanation 
59,60 Blank Indicates that this field is not a control field 
L1-L9 Associates a control-level indicator with the field 


you specify in columns 53 through 58 


Rules 

e You can specify control-level indicators for primary and secondary 
files only. 

* You can assign control-level indicators in any order. 


e Control-level indicators are ranked from highest (L9) to lowest (L1). 
When a control break causes VAX RPG II to set on a control-level 
indicator, all lower control-level indicators are set on. All control-level 
indicators are set off after detail-time output. 
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e When you assign the same control-level indicator to more than one 
field, the fields are referred to as split-control fields. In this case, 
fields must be either all numeric or all alphanumeric and described on 
adjacent lines. Split-control fields do not need to be the same length. 


¢ Fields with different control-level indicators can overlap in a record. 


e You do not need to specify the same number of control fields for all 
record types. 


e VAX RPG II initializes control fields to hexadecimal zeros. This usually 
causes a control break to occur on the first record with a control field. 
Because of this, VAX RPG II bypasses total-time calculation and output 
operations for this cycle. 


¢ You cannot specify control-level indicators for binary data or look- 
ahead fields. Also, you cannot specify a control-level indicator when 
you specify an array name in columns 53 through 58. 


e VAX RPG II ignores decimal positions and signs (positive and nega- 
tive) when determining a control break. 


e Because field names are ignored, you can assign the same control-level 
indicator to multiple fields with the same name. 


e If you assign the same control-level indicator to more than one field | 
in different types of records, the fields must be either all numeric with 
the same number of digits or all alphanumeric with the same number 
of characters. 


° The total length of a split-control field must be the same length as 
other uses of the same control-level indicator. 


e If a control field contains packed decimal data the zoned decimal 
length, which is two times the packed decimal length minus one, is 
considered the length of the field. 


See Section 15.6.18 for information about using a field-record-relation 
indicator with control fields. 


In the following example, each record in the file EMPLOYEE contains the 
same three fields; NAME, ADDRES, and DEPTNO. The length of NAME 
is 30 characters; the blank in column 52 indicates that the contents of the 
field are alphanumeric. The length of ADDRES is 20 characters. Both 
fields are assigned the same control-level indicator (L8), so they are split- 
control fields. DEPTNO contains more significant data and is assigned 

a higher-level control-level indicator. When the contents of DEPTNO 
change, VAX RPG II sets on both control-level indicators (L9 and L8). 
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Sequence (AA-ZZ, 01-99) 
Number (1-N) 
1Optional/External (OU) Decimal positions 





| 
| 
| }tRecord identifying indicator | Control level 
1 atl | | Match field 
| 1Il + Identifying codes + Format = | | | Fld rec rel 
File Pale d. 1 | (PB) Field | J I 
name Pill | C ¢ Cl IField tname | 1 | Field 
| Path t Z z Z| llocation! | | | | indicatrs 
Il ! 111 Pos NDcPos NDcPos NDc IFr To il ie ee 
0 } 4 | 2 | kj | rt | 5 | 6 | 7 | 
1234567890123456 7890123456 7890123456 7890123456 7890123456789012345678901234567890 
¥% TE Se ee HHH H EH wun, 
IEMPLOYEEAA 05 1 CA 31 CC 
I OR 99 123ND6 
I 1 30 NAME L8 
I 31 51 ADDRESL8 
I 123 1230DEPTNOLY 
. ZK-4490-85 


15.6.17 Matching Fields 


Use columns 61 and 62 to specify matching fields. Matching fields instruct 
VAX RPG II to compare the fields in records from one or more files. When 
the contents of a field from a primary file match the contents of a field 
from a secondary file, VAX RPG II sets on the matching-record indicator 
(MR). 


You can use the matching-record indicator to condition calculation and 
output operations. 


Column Allowable 


Number Values Explanation 
61,62 Blank Indicates that this field is not a matching field. 
M1-M9 Identifies a matching field. See Chapter 8 for 
information about matching fields and multifile 
processing. 
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You can use matching fields with one file to perform sequence check- 
ing or with multiple files to control the order of processing records. 
See Chapter 8 for information on multifile processing. 


You can compare only those fields from records in primary and 
secondary input and update files. 


You can compare up to nine different fields in a single record. 


If you specify more than one matching field for a record type, all 
the fields are logically concatenated and treated as one continuous 
field. The fields are combined according to descending sequence (M9 
through M1) of matching field values. 


The program performs sequence checking for all record types with 
matching field specifications. An error in sequence causes a run-time 
error and terminates the program. 


You must define the same number of matching fields and the same 
matching field values (M1 through M9) for all those records that 
contain matching fields. 


You can overlap matching fields in a single record. 


Whenever you use more than one matching code, all matching fields 
must match before VAX RPG II sets on the matching-record indicator 
(MR). 

Matching fields assigned the same matching code (M1 through M9) 
must be either numeric with the same number of digits, or alphanu- 
meric with the same length. 


Not all files or all record types within one program must have match- 
ing fields. However, at least one record type from each of two files 
must have matching fields if the files are to be matched. 


If the matching field contains packed data the zoned decimal length, 
which is two times the packed length minus one, is considered the 
length of the matching field. It is valid to match a packed field in one 
record against a zoned decimal field in another if the digit lengths 
are identical. The length must always be odd because the length of a 
packed field is always odd. 


The file sequence you specify in column 18 of the File Description 
specification must be the same for the files you compare—all 
ascending or descending. 


You can check the sequence of a single sequential file using M1 
through M9 codes to designate the sequence. If the file is out of 
sequence, a run-time error occurs. 
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You cannot specify matching values for binary data and look-ahead 


fields. You cannot specify matching values when you specify an array 
name in columns 53 through 58. 


If you specify an alternate collating sequence, VAX RPG II uses the 
alternate sequence when comparing the values in matching fields 
containing alphanumeric data. 


VAX RPG II ignores field names, so fields from different record types 
can have the same name and match code. 


When you specify an ascending sequence check, VAX RPG II initial- 
izes the matching value to hexadecimal zeros. When you specify a 
descending sequence check, VAX RPG II initializes the matching value 
to hexadecimal FFs. VAX RPG II initializes the matching value of a 
numeric field to zero. 


VAX RPG II compares matching fields containing numeric data based 
on their absolute values because decimal positions and signs are 
ignored. 


Matching fields cannot be split; the same matching field value cannot 
be used more than once for one type of record. 


When you specify a matching field value for a field without a field- 
record-relation indicator, you must specify all matching field values 
once without a field-record-relation indicator. If all matching fields 
are not common to all records, use a dummy matching field. See 
Section 15.6.19 for information on using a field-record-relation indica- 
tor with matching fields. 


Matching fields are independent of control-level indicators. 


See Chapter 8 for examples of matching fields. 


15.6.18 Field-Record-Relation Indicator 


Use columns 63 and 64 to specify field-record-relation indicators that 
control the conditions under which VAX RPG II extracts data from the 
input buffer into a field. These conditions include control breaks, matching 
records, halts, and external indicators. 


The most common use of a field-record-relation indicator is as a record- 
identifying indicator to group several different record types in an OR 
relationship and associate fields with a particular record type. You can 
also use field-record-relation indicators to extract data if a particular 
external indicator is on. 
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Column Allowable 


Number Values Explanation 
63,64 Blank Indicates no field-record-relation indicator 
01-99 Indicates that the field-record-relation indicator is a 


record-identifying indicator 
L1-L9 Indicates that the field-record-relation indicator is a 
control-level indicator 


MR Indicates that the field-record-relation indicator is 
the matching-record indicator 


U1-U8 Indicates that the field-record-relation indicator is 
an external indicator 


H1-H9 Indicates that the field-record-relation indicator is a 
halt indicator 


The following rules apply to field-record-relation indicators used with 
control and matching fields: 


You must specify control fields and matching fields without field- 
record-relation indicators before you specify those fields with them. 


When the field-record-relation indicator associated with a matching 
or control field is on, VAX RPG II uses that field as the control 

or matching field for the record rather than the same control or 
matching field specified without a field-record-relation indicator. 
Otherwise, VAX RPG II uses the control or matching field without the 
field-record-relation indicator. 


When you have not defined an entire set of matching fields without 
a field-record-relation indicator, a full set of matching fields must be 
assigned to each field-record-relation indicator used with a matching 
field. 


You must use the same field-record-relation indicator for split-control 
fields. You must describe the split-control fields on consecutive lines. 


You must group control and matching fields that use field-record- 
relation indicators according to indicator. 


Field-record-relation indicators for control and matching fields can 
be only 01 through 99 or H1 through H9 indicators. Also, the field- 
record-relation indicator for control and matching fields must be a 
record-identifying indicator specified on either the preceding record 
definition line, or in one of the lines in an OR relationship. 
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If you have two records with eight fields each, and the first seven fields are 
the same but the last field is different, you can use the record-identifying 
indicator as the field-record-relation indicator to condition the field that is 
different, rather than defining all eight fields for both records. 


In the following example, the last two fields were conditioned with the 
same record-identifying indicators in lines 1 and 2. If the job code is 2, 
VAX RPG II uses the bonus value from positions 72 through 74. If the 
job code is not 2, VAX RPG II will use the bonus value from positions 75 


through 77. 


Sequence (AA~ZZ, 01-99) 

| Number (1-N) 

| lOptional/External (OU) 

Record identifying indicator 


Decimal positions 
| Control level 
| | Match field 


I tt 
1 dtl 
. | {11 + Identifying codes + Format | | | Fld rec rel 
File Putt | 1 | (PB) [Field I J | 
name Pili ¢ ¢ Cl IField tIname | ! | Field 
| Puli Z z Z! llocation| | | | | indicatrs 
I| 1 tll VI 11 1+-0 






| 
H¥ He RRR H--- RR 
IEMPLOYEEAA O1 71 C2 
OR 02 71NC2 


¥--- 


Sete ee ete et et ei 
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Pos NDcPos NDcPos NDe IFr To 
2 | 3 | 4 


| 7 | 
8901234567890 
* 





| 
0123456 


* ISs 
K TS Rea) 
* BS] 


a TS 
ax Tes: 


10 FNAME 
12 MINIT 
33 LNAME 
54 ADDRES 
60 STATE 
700PHONE 
7L0J0BCDE 
742BONUS 
772BONUS 


01 
02 
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15.6.19 Field Indicators 


Use columns 65 through 70 to specify field indicators. Field indicators 
check the condition of numeric or alphanumeric fields when they are 
extracted from the input record. Once checked, the field can be in one of 
three conditions: 


1. 


If the numeric field in columns 53 through 58 is greater than zero, 
the condition is positive and VAX RPG II sets on the field indicator in 
columns 65 and 66. Otherwise, VAX RPG II sets off the indicator. 


If the numeric field in columns 53 through 58 is less than zero, the 
condition is negative and VAX RPG II sets on the field indicator in 
columns 67 and 68. Otherwise, VAX RPG II sets off the indicator. 


If the numeric field in columns 53 through 58 is equal to zero, or if 
the alphanumeric field in columns 53 through 58 contains blanks, the 
condition is null and VAX RPG II sets on the field indicator in columns 
69 and 70. Otherwise, VAX RPG II sets off the indicator. 


Column Allowable 


Number Values Explanation 
65-70 Blank Indicates no field indicators. 
01-99 Associates a field indicator with a field. 
H1-H9 Indicates that the field indicator is a halt indicator. 


Halt indicators check for errors in data. For exam- 
ple, you can specify a halt indicator to check for 
zeros in a numeric field. If VAX RPG II processes 
the record and finds a zero in the field, it sets on 
the halt indicator that results in a run-time error. 


Use columns 65 through 70 to check numeric fields. 
Use columns 69 and 70 to check alphanumeric fields. 


You can use the same field indicator for more than one field in 
different record types. The status of the indicator depends on the 
record type last read. 


Columns 65 through 70 must be blank when columns 53 through 58 
contain an array without an index or look-ahead fields. 


You can assign one or more field indicators to a numeric field. 
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15.7 Description 


The Calculation specification allows you to describe the calculations you 
want to perform and to define their order in the following ways: 


e Entries in columns 7 through 17 control when a calculation is to be 
performed. 


¢ Entries in columns 18 through 53 describe the type of calculation to 
be performed. 


e Entries in columns 54 through 59 specify which indicators the program 
sets on or off as a result of the calculation. 


There are two general rules: 


1. Specify each calculation on a single line; arrange the calculations in 
the order you want them executed. 


2. Specify detail-time calculations first, then total-time calculations and, 
finally, calculations in subroutines. 
15.7.1 Calculation Specification Format 
The format of the Calculation specification is as follows: 


Field length 
Control level | Decimal positions 
| IHalf adjust (H) 


| 
| Indicators Operation 1 lt 
| | |lResulting 
It. Factor | Factor Result! Ilindicators 
1 | 1 | 2 field | IIlt+t- 0 
Ch NxxNxxNxxt | | ft - £ > <= +- Comments --+ 


I 1 | 2 | 3 | 4 | a) | 5) | 7 
tT RTR eA ea cl Aa OA ERR SAE Eee 
HX % % % * H--HEE HK ¥ 
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Calculation Specification (C) 


Use column 6 to identify the type of specification for every program line. 


Column 
Number 


6 


15.7.3 Control Level 


Allowable 
Values 


Cc 


Explanation 


Indicates that this program line is a Calculation 


_ specification. 


Use columns 7 and 8 to indicate whether the calculation is performed at 
detail time, at total time, or is part of a subroutine. 


Column 
Number 


7,8 


Allowable 
Values 
Blank 

LO 


L1-L9 


LR 


SR 


Explanation 


Performs the calculation at detail time, or indicates 
that the program line is part of a subroutine. 


Performs the calculation at total time for each 
program cycle. 


Performs the calculation at total time after a 
control break occurs, or when you use the SETON 
operation to set on the control-level indicator, or 
when the indicator is set on as a record-identifying 
indicator, or when the indicator is set on as a 
resulting indicator in a calculation. 


Performs the calculation at total time after the 
program processes the last record, or when you 

use the SETON operation to set on the last-record 
(LR) indicator, or when the indicator is set on as a 
record-identifying indicator, or when the indicator is 
set on as a resulting indicator in a calculation. 


Indicates that the calculation is part of a subroutine. 
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Column Allowable 
Number Values Explanation 


AN or OR Establishes a relationship between two program 
lines. If you use AN, the conditions for the in- 
dicators in both program lines must be satisfied 
before VAX RPG II executes the calculation. If you 
use OR, the conditions for the indicators in one 
program line or the other must be satisfied before 
VAX RPG II executes the calculation. 


You can use an unlimited number of AN or OR 

- program lines with up to three indicators on each 
line to condition a single calculation. The last 
line in an AN or OR relationship specifies the 
calculation. 


Additional Information 


You can specify the following declarative statements in total-time calcula- 
tions and optionally leave columns 7 and 8 blank: 


e EXTRN 
e  GIVNG 
e PARM 

e PARMD 
e PARMV 
e =6PLIST 

e TAG 
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In the following example, the L1, L2, L3, and LR control-level indicators 
perform calculations at total time after a control break occurs or when the 
SETON operation code sets on the indicator. 


Field length 
Control level | Decimal positions 
lHalf adjust (H) 
II 





| 
| Indicators Operation | 
1 | | | | Resulting 
1 | Factor | Factor Result! Ilindicators 
1 | i | 2 field | Il+- 0 
Cl NxxXNXXNXx | i. | I | |l> < = +- Comments --+ 
0 | 1 | 2 | 4 | 5 | 6 J 7 | 
EE LCRA EULA UTE AE LA OR, 
HH ¥ % %  R—— KKH KH HH 
Cx Total calculations: 
Cx 
CLi SETOF LRLIL8 
CLi SETOF . L7L6L5 
CLi SETOF L4L3L2 
CL4 i DSPLYS 
CLi SETOF L@L3LR 
Cx 
CL4i EXSR HILLS 
CLi PELHAM TAG 
Cx 
CLi "L 2’ DSPLYS 
CL3 of Wee DSPLYS 
C¥ 
CL3 EXSR CARROL 
cLi GOTO PETERB 
Cx 
CL1 "Lh 4? DSPLYS 
CL2 6 COMP BERRY 313233 
CLR SETOF 24 
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15.7.4 Indicators 


Use indicators in columns 10, 11, 13, 14, 16, and 17 to condition the 
calculations you specify in columns 28 and 32. You can specify up to 
three indicators on a program line; precede the indicator with N to cause 
VAX RPG II to perform the calculation only when the indicator is not 
on. Use columns 9 through 11 to describe the first indicator, columns 12 
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through 14 to describe the second, and columns 15 through 17 to describe 
the third. Using the indicators in this way forms an AND relationship. 


Column Allowable 


Number Values Explanation 

10 Blank Performs the calculation whenever the conditions 
13-14 specified in columns 7 and 8 are satisfied. 

16-17 

11 * Repeat line. If the preceding line was performed, 


then the * line will be performed. 


Indicator Performs the calculation when the conditions for 
the indicator are met. 


9,12,15 N Causes VAX RPG II to perform the calculation 


only when the indicators associated with N are not 
set on. N in column 9 conditions the indicator in 
columns 10 and 11. N in column 12 conditions the 
indicator in columns 13 and 14. N in column 15 
conditions the indicator in columns 16 and 17. 


Additional Information 


You can use one of the following indicators in columns 10 and 11, 11, 13 
and 14, and 16 and 17: 


Asterisk (*) 
Record-identifying (01-99) 
Control-level (L1-L9) 
Last-record (LR) 
Matching-record (MR) 

Halt (H1-H9) 

External (U1-U8) 

Overflow (OA-OG, and OV) 
KA-KZ and K0-K9 


VAX RPG II performs total calculations for a control break before per- 
forming detail-time calculations for the record that causes the control 
break. 
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When multiple calculation lines are to be performed for the same set of 
conditions, you must specify the conditions only on the first line; indicate 
the same conditions for the successive lines with an asterisk indicator (*) 
in column 11. The result is that if the preceding line is performed, the 

* line will be performed. If there are additional conditions that must be 
met before the * line is to be performed, those conditions may be stated in 
columns 12 through 17. 


Halt indicators in columns 10, 11, 13, 14, 16, and 17 cause VAX RPG II 
to bypass the operation when it finds an error in the input data or in a 
previous calculation. VAX RPG II processes the record that causes the 
etror before stopping your program. In this case, the record in error could 
cause an error in calculation before your program terminates. 


Depending on the relationship between indicators in columns 7 and 8 and 
columns 9 through 17, the actions VAX RPG II takes will vary as follows: 


e When you specify a control-level indicator in columns 7 and 8 and 
a matching-record indicator in columns 9 through 17, MR indicates 
the result of matching the previous record rather than the record 
just read that caused a control break. VAX RPG II executes all the 
operations conditioned by control-level indicators before determining 
the matching condition of the record just read. 


e¢ When you use a control-level indicator in columns 10, 11, 13, 14, 16, 
and 17 instead of in columns 7 and 8 of the Calculation specification, 
VAX RPG II performs the calculation on the first record of a new 
control group at detail time. 


¢ Ina single program cycle, VAX RPG II performs all operations con- 
ditioned by the control-level indicators in columns 7 and 8 before it 
performs the operations conditioned by the control-level indicators in 
columns 9 through 17. 


e If you condition a calculation with a last-record indicator in columns 
9 through 17 when columns 7 and 8 are blank, the calculation is 
performed only if the last-record indicator is set on during detail-time 
calculations. If the last-record indicator is set on when VAX RPG II 
reaches the end-of-file or during total-time calculations, VAX RPG II 
does not perform detail-time calculations. 
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In the following example, the record-identifying indicators 01, 02, and 03 
must be on to perform the calculation SALARY * BONUS1 = GROSS. In 
the second program line, the indicator 04 must be off and indicator 05 
must be on to perform the calculation SALARY * BONUS2 = GROSS. 


Field length 
| 


Control level Decimal positions 


| IHalf adjust (H) 
| Indicators Operation 1 oll 
1 | | | IiResulting 
1 | Factor | Factor Result! Ilindicators 
| | | 2 field | Jl+- 0 


Cl NxXxNXXxNXx | | la: | | tl> < = +- Comments --+. 
| 1 





3 4 | 5 | a) | 7 | 
12345678901234567890123456789012345678901 2545678901 234567890123456 78901 234567890 
HK % % x % ¥% H--KHEK HH * 
C Of 02 O3SALARY MULT BONUS1 GROSS 
C N04 05 SALARY MULT BONUS2 GROSS 
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15.7.5 Factors 1 and 2 


Use columns 18 through 27 and 33 through 42 to provide the operands 
for the calculation you specify in columns 28 through 32. Use columns 
18 through 27 for factor 1 and columns 33 through 42 for factor 2. The 
operands you use depend on the operation you specify. See Chapter 16 
for information on operations and the operands they require. 
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Column 
Number 


18-27 or 
33-42 


18-27 or 
33-42 


8-74 


Allowable 
Values 


Field name 


Literal 


Long 
character 
literal 


Calculation Specification (C) 


Explanation 


Names the field that contains data. These are the 

same fields you defined in columns 53 through 58 
of the Input specification or in columns 43 through 
48 of the Calculation specification. 


Specifies an alphanumeric or numeric constant. 
Numeric literals can consist of the digits 0 through 
9, one decimal point, and one arithmetic sign. 
Numeric literals cannot exceed 10 characters and 
cannot contain blanks. You must specify the sign in 
the leftmost character position. 


Alphanumeric literals can be up to eight characters 
including blanks. You must enclose alphanumeric 
literals in single quotation marks (for example, 
‘NH’). Use the keyboard apostrophe mark for 

the single quotation mark. If you want to use 

an apostrophe in a literal, you must enter two 
consecutive apostrophes (for example, it’s). 


Specifies an alphanumeric constant that contains 

1 to 460 characters. A double quotation mark (") 
is placed in the first character of the field on the 
specification. The rest of the field is left blank. On 
the next line, a double quotation mark (") is placed 
in column 7. Columns 8 through 74 contain the 
character literal, which must be enclosed within 
single quotation marks (‘). The character literal can 
be anywhere on the line. 


If you wish the character literal to continue on the 
next line, follow the ending single quotation mark 
with a plus sign (+) and continue the literal in 
the same manner on the next specification. All the 
rules for “normal” character literals apply to the 
long character literal placed in columns 8 through 
74. 


If more than one long character literal is entered on 
a Calculation specification, the character literal for 
the first (leftmost) entry is on the next specification, 
followed by the character literal for the second 
entry on the specification after that. 
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Column Allowable 
Number Values 


Table or 
array 


Subroutine 
name 


_ Special 
words 


Label 


File name 


Explanation 


Specifies the table name, array name, or array 
element you specified previously in an Extension 
specification. 

Specifies one of the following components of a 
subroutine: BEGSR (marks the beginning of a 
subroutine) and EXSR (executes a subroutine). 


Specifies one of the following special words: 
UDATE, UMONTH, UDAY, UYEAR, PAGE, PAGE1 
through PAGE7, *IN, and *INxx. See Chapter 9 for 
information on special words. See Chapter 7 for 
information on *IN and *INxx. . 


Specifies the label for TAG, GOTO, and ENDSR 
operations. See Chapter 16 for information on TAG, 
GOTO, and ENDSR operation codes. 


Specifies the file name for CHAIN, DSPLY, READ, 
SETLL, or FORCE operations. See Chapter 16 for 
information on specifying files for these operations. 


Note that you must left justify the entries in Factors 1 and 2 unless they 
are numeric literals, which must be right justified. 


In the following example, the literal 'All work and no play makes Jack a 
dull boy.’ is moved to the field SHINE: 


| 4) | ) | 7 | 





I 2 | 3 | 4 
12345678901234567890125456789012545678901234567090123456789012345678901234567090 


4H OX % 


NOVE iu 


* H--HRK HHH 
SHINE 80 


C 
C" “All work and no play make Jack a dull boy.’ 
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Calculation Specification (C) 


This example shows a long character literal continuing on another line: 





) | i | 2 | 3 | 4 I 5 | 6 I 7 | 
SE AIEEE LTE TERI LL eR ce ee 

HX X # * % H--HRE HORE 

¢ MOVE " SHINE 80 

cn "All work and no play make Jack ‘+ 


C" ’a dull boy.’ 
: ZK-4496-85 


15.7.6 Operation Code 


Use columns 28 through 32 to specify the operation code that indicates 
which calculation to perform on the operands you specified in columns 18 
through 27 and 33 through 42. See Chapter 16 for more information on 
operation codes. 


Column Allowable 


Number Values Explanation 
28-32 Operation Performs the action specified by the operation code. 
code See Chapter 16 for information on operation codes. 


15.7.7. Result Field 


Use columns 43 through 48 to provide the result field that will contain 
the outcome of the calculation you specified in columns 18 through 42. 
You can use a field you specified previously in an Input, Calculation, or 
Extension specification or use columns 49 through 52 to define its length 
and decimal positions. 


Column Allowable 
Number Values Explanation 


43-48 Name Identifies the result field. The result field can 
contain a field name, table or array name, array 
element, or one of the following special words: 
PAGE, PAGE1-7, *IN, or *1Nxx. 
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¢ The result field name can be any combination of alphanumeric charac- 
ters; the first character must be alphabetic. Embedded blanks are not 
allowed. 


e You cannot use a look-ahead field, a field defined by an EXTRN 
operation, UDATE, UDAY, UMONTH, or UYEAR as a result field. 


15.7.8 Field Length 


If you use the Calculation specification to define a result field, use columns 
49 through 51 to define the length of the result field you specified in 
columns 43 through 48. Otherwise, you can leave columns 49 through 51 
blank. To prevent undefined or truncated results, make sure the length of 
the result field is long enough to hold the largest possible result. 


Column Allowable 


Number Values Explanation 
49-51 1-999 Specifies the length of the result field 
Rules 


e The maximum length for numeric data is 15 digits. 
e The maximum length for alphanumeric data is 999 characters. 


e If the field is described elsewhere in the program and an entry is made 
in columns 49 through 51, both entries must specify the same length. 


¢ Right justify this entry. 
e Leading zeros can be omitted. 
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15.7.9 Decimal Positions 
If you use the Calculation specification to define the result field and the 


result field contains numeric data, use column 52 to specify the number of 
positions to the right of the decimal point. 


Column Allowable 


Number Values Explanation 
52 Blank Indicates that this field contains alphanumeric data 


or that the result field has been defined elsewhere 


0-9 Specifies the number of positions to the right of the 
implied decimal point 


e If the field has been described previously in the program and an entry 
is made in column 52, both entries for decimal positions must be the 
same. 

¢ The number you specify in this column must be smaller than the 
number in columns 49 through 51. 


e If the result field contains alphanumeric data, leave this column blank. 


e¢ When the result is numeric, but has no decimal positions, you must 
specify zero. 


15.7.10 Half Adjust 


Use column 53 to specify whether VAX RPG II is to round the numeric 
data in the result field. VAX RPG II adds five to the position immediately 
to the right of the last digit and puts the new value in the result field. 
VAX RPG II performs the addition on the absolute value of the number. 
For example, if the result of an arithmetic operation is 123.456 and the 
result field specifies two decimal positions, VAX RPG II half adjusts the 
value in the result field to 123.46. 
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Column Allowable 


Number Values Explanation 
53 Blank Performs no half adjusting 

H Half adjusts the numeric data in the result field 
Rules 


e You cannot half adjust the result field of an MVR operation or a DIV 
operation that is followed immediately by an MVR operation. 


e You cannot half adjust alphanumeric data. 
Additional Information 


VAX RPG II sets resulting indicators according to the value of the result 
field after half adjusting. See Table 16-1 in Chapter 16 for a list of 
operation codes that allow you to specify half adjust. 


15.7.11 Resulting Indicators 
Use columns 54 through 59 to enter resulting indicators that test the out- 


come of a calculation. You can use these resulting indicators to condition 
other calculation or output operations, or to establish field-record relations. 
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Column Allowable 


Number Values Explanation 
54-59 01-99 Uses a record-identifying indicator as the resulting 
indicator. 
H1-H9 Uses a halt indicator as the resulting indicator. 
K0-K9 Uses a K indicator as the resulting indicator. 
KA-KZ . 
L1-L9 Uses a control-level indicator as the resulting 
indicator. 
LR Uses a last-record indicator as the resulting 
indicator. 
OA-OG, OV Uses an overflow indicator as the resulting indicator. 
U1-U8 Uses an external indicator as the resulting indicator. 
Rules 


A resulting indicator is set on if the condition specified is satisfied. If 
the specified condition is not satisfied, the resulting indicator is set off. 
See Chapter 16 for information on how resulting indicators are used 
with each operation code. 


If you use the same indicator to test the results of more than one 
operation, the last operation determines the indicator setting. 


You cannot use resulting indicators when the result field contains a 
nonindexed array. 
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Additional Information 


After a resulting indicator is on, it remains on until one of the following 
occurs: 


¢ The operation is repeated and the result resets the indicator 
¢ The conditions the indicator specifies are not met 


¢ The indicator is set off by another method (such as the SETOF 
operation) 


Using a control-level indicator as a resulting indicator does not automati- 
cally set on lower-level indicators. 


Using an external indicator as a resulting indicator allows you to set the 
indicator, then to test the indicator value after the program exits. 


15.7.12 Comments 


Use columns 60 through 74 for comments. 


Column Allowable 


Number Values Explanation 
60-74 Any Documents the program line 
character 
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15.8 Description 


The Output specification describes the records and fields in an output, 
update, or input (with the ADD option) file. Columns 7 through 37 
describe the record and columns 23 through 70 describe the position and 
format of each field in the record. | 


15.8.1 Output Specification Format 


The format of the Output specification is as follows: 





Type (HDTE) Edit codes , ONOCR - 
Fetch ofl / Rel (FR) |X seem eeneeen 
| |Space | Y date edit YYdiAjd 
Ill Skip | Z zero suppress Y N 2 B K 
Wit | NY 3 CL 
ltt 1 © Indicators IBlank-after (B) NN 4 D M 
File Hl df Field IlEnd position 
name Wt | name [Il Format (PB) 
| rth | | | Itt | 
0l 11BAB A NxxNxxNxx | Vt I+ Constant or edit word + 
0 | 1 | 2 | 3 | 4 | a) | 6 7 | 
12345678901234567890123456 78901235456 7890123456 7890123456 78901235456 7890123456 7890 
#% HHEKE % % % HER HH Here 
ZK-4497-85 


15.8.2 Specification Type 


Use column 6 to identify the type of specification for every program line. 


Column Allowable 


Number Values Explanation 
6 O Indicates that this program line is an Output 
specification 
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15.8.3 File Name 


Use columns 7 through 14 to name the output, update, or input (with the 
ADD option) file. 


Column Allowable 


Number Values Explanation 
7-14 File name Identifies the name of the output file 
Rules 


e Use the same file name you specified in the File Description specifi- 
cation. An output file can be a file you specified as an output file, an 
update file, or an input file with A in column 66 of the File PeecHnOn 
specification. 


e = Left justify this entry. 


e If columns 7 through 14 are blank, VAX RPG II assumes that the 
information in this program line describes a field or record from the 
file last named. 


All the records for a single file need not be described together. 


15.8.4 AND and OR Lines 


If you need more than three indicators to condition record output, or if 
you want to output a record under a number of conditions, use columns 
14 through 16 to enter AND or columns 14 through 15 to enter OR. 


Column Allowable 
Number Values Explanation 


14,15 OR Performs the output operation when the conditions 
for all indicators in columns 23 through 31 in either 
program line are met 


14-16 AND Performs the output operation when the conditions 
for all indicators in columns 23 through 31 in both 
program lines are met 
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Rules 

e You must use at least one indicator on a program line in an OR or 
AND relationship. 

e If you use AND, columns 17 through 22 must be blank. 

e If you use AND or OR, columns 7 through 13 must be blank. 


e You can use AND and OR lines only with record description entries, 
not with field description entries. 


e You can specify an unlimited number of AND or OR lines. 
In the following example, if these conditions are satisfied, VAX RPG II 
writes the specified fields and constants: 


— Indicator 01 is off 
— OR, indicator 01 is on 
— AND, indicator 23 is off 


Type (HDTE) Edit codes , © No CR 
IFetch ofl / Rel (FR) Rc. 0 60 RRR eeee 
| |Space | Y date edit YYiaédJ 
111 Skip | Z zero suppress Y N 2 B K 
Ht | NY 3 CL 
ltt t= Indicators IBlank-after (B) N N 4 D WM 
Ht dof Field I!End position 
il | | name [ll Format (PB) 
idol | Ht ot 
1 1BAB A NxxNxxNxx 1 1 l+ Constant or edit word + 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 
HEHE H % % HH ~~ HH 
OR NO4 
OR 01 
AND N23 
PN 3 
01 28 ‘01’ 
PNAME 10 
WHOUSE 12 
COLOR 17 
WEIGHT 20 
QTY 24 


oqoooaooco9c0 Aa & 


2K-4498-85 
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15.8.5 Record Type 


Use column 15 to specify the point in the VAX RPG II program cycle at 
which a record is output. Heading records are normally used to describe 
the heading information in the output report, such as column names, page 
numbers, and the date. Detail records contain the data from input and 
calculation operations at detail time. Total records usually contain the 
data from the result of calculations on several detail records at total time. 
Exception records are written as a result of using the EXCPT operation in 
a Calculation specification. 


Column Allowable 


Number Values Explanation 
15 Blank Indicates that this program line describes a field or 
constant 
H Indicates that this program line describes a heading 
record 
D Indicates that this program line describes a detail 
record 
a) Indicates that this program line describes a total 
record 
E Indicates that this program line describes an 


exception record 


e You must specify a record type for every output record. 


¢ Records of the same type are tested for output and written in the order 
in which you specify them in the Output specifications. 


Additional Information 


There is no difference between a heading record and a detail record. The 
different entries are for documentation purposes only. 


The following example defines heading, detail, total, and exception 
records. 
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| name [lt Format (PB) 
| | in| | 
AB A NxxNxxNxx 1 aa {+ Constant or edit word + 


age 4 [ye l 3 r Nl 5 Nl 6 | 7 ] 
1234567890123456 789012346 709012348670901254567890125456789012545678901254567890 


Type (HDTE) Edit codes , ONOCR - 
IFetch ofl / Rel (FR) | X ToRueeainpan Angas 
| 1Space | Y date edit YYiad 
Htl Skip | Z zero suppress Y N 2 B K 
Hl | | NY 3CL 
111 1 Indicators IBlank-after (B) NN 4 D M 
File Mbt | Field |lEnd position 
name Ith | 
ltt 
118 






HR HRHEXH H % RRK—-—-—-HE 
OOUT44A E 12 

0: OR 16 

0 OR LR 

0 N 3 

0 PNAME 10 

0 WHOUSE 12 

0 COLOR = 17 

0 WEIGHT 20 

0 QTY 24 

0 26 'E? 
0 N12 16 28 16" 
0 12 04 2B 742’ 
0 LR 28 LR’ 
0 H 

0 N 3 

0 PNAME 10 

0 WHOUSE 12 

0 COLOR 17 

0 WEIGHT 20 

0 QTY 24 

0 26 'H’ 
0 04 28 04’ 
0 D 17 

0 OR NO4 

0 OR 04 Of 

0 AND N23 

0 N 3 

0 04 28 01" 
0 PNAME 10 

0 WHOUSE 12 

0 COLOR 17 

0 WEIGHT 20 

0 QTY 24 

0 26 'D’ 
0 T 

0 N 3 

0 PNAME 10 

0 WHOUSE 12 

0 COLOR = 1? 

0 Of 28 01" 
0 WEIGHT 20 

0 QTY 24 

0 26 'T! 


ZK-4499-85 
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15.8.6 ADD and DEL Options 


Use columns 16 through 18 to add and delete records. See Chapter 8 for 
information on adding and deleting records. 


Column Allowable 


Number Values Explanation 
16-18 ADD Adds a record to an input, output, or update 
file with an indexed, direct, or sequential file 
organization 
DEL Deletes the last record read in the update file with 


an indexed or direct file organization 


e You can add records to input, output, and update files that reside on 
disk. Therefore, the File Description specification must contain DISK 
in columns 40 through 46 and A in column 66. 


e You can delete records only from update files that reside on disk. 


e ADD or DEL must appear on the same line that defines the record 
type for the record you want to add or delete. 


e Ifa line in an OR relationship follows an ADD or DEL entry, the ADD 
or DEL entry applies to both lines. 


The following example adds records to the file: 


0 | 1 | 2 | 3 | 4 | 4) | ts) I ri | 





1234567890123456789012345678901234567890123456789012345678901 2345678901 234567890 
OOUT43A DADD NiP 


0 N 3 
0 PNAME 10 
0 WHOUSE 12 
0 COLOR 17 
0 WE TGHT 20 
0 QTy a4 


ZK-4500-85 
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The following example deletes the last record read from the update file: 


Type (HDTE) Edit codes , ONOCR - 

IFetch of] / Rel (FR) | X 2 tenn nnennn 

| |Space | Y date edit YY iad 

Itt Skip | Z zero suppress Y N 2 B K 

HH I | NY 3 CL 

It] |) = Indicators IBlank-after (B) NN 4 D M 

File Hi tt Field j!End position 
name Ill | | name {11 Format (PB) 
| htt | | | th | 
0l 11B It 1+ Constant or edit word + 
I 


0 | i | I 3 4 | 5 | 7 | 
123456789012345678901234567890123456 7890123456 7890123456 7890123456 78901234567890 
HE HEKEE & * *® RER-—-—-EE sae 
OOUT45B EDEL N25 
OOUT45C =EDEL N25 





ZK-4501-85 


15.8.7 Fetch Overflow or Release 


Use column 16 to specify fetch overflow for a printer file, or release for 
a WORKSTN file. Fetch overflow causes VAX RPG II to check whether 
the overflow indicator assigned to the printer output file is on before 
printing total, detail, or exception records. See Chapter 9 for information 
on overflow. 


Release terminates processing of the WORKSTN file. See Chapter 6 for 
information on release. 


Column Allowable 


Number Values Explanation 
16 F Executes the overflow routine if overflow has 
occurred 
R Release is performed on the WORKSTN file 
Rules 


e An entry in this column is valid only for printer output files with 
overflow lines (F), or a WORKSTN file (R). 


e Do not specify an overflow indicator on the same line as fetch 
overflow. 
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e If you specify an OR relationship between two lines, you must specify 
fetch overflow for each record type that requires it in both lines of the 
OR relationship. 


Additional Information 


VAX RPG II fetches an overflow routine when overflow occurs and all 
conditions specified by the indicators in columns 23 through 31 are met. 
When you specify fetch overflow, only overflow output associated with 
the file containing the executed fetch routine is output. The overflow 
routine does not automatically advance to the next page. 


The following example specifies fetch overflow: 


name 
| 


| name ||| Format (PB) 
| | | 


Type (HDTE) Edit codes , 9 NOCR - 
iFetch of] / Rel (FR) 1X 9 “Seeseesses-= 
| |Space | Y date edit YYdiaAaédJ 
111 Skip | Z zero suppress Y N 2 B K 
Wit | | NY 3 CL 
It! | Indicators IBlank-after (B) N N 4 DM 
File Hit | Field JlEnd position 

Vit | 

Vit | 

11 


11 
1 1+ Constant or edit word + 










| 2 I R) | 4 I a) | 6 I 7 | 
1234567890123456 7890123456 7890123456 7890123456 7890123456 789012345678901234567890 
HX HAKRE HF % HHH —- HE , 
QOUT66A EF 1 Of 
0 AND 02 03 





ZK-4502-85 


15.8.8 Space Before and Space After 


Use columns 17 and 18 to define the format of a printer output file. Use 
column 17 to specify the number of lines to advance before printing the 
next line of output. Use column 18 to specify the number of lines to 
advance after printing a line of output. 


15-120 VAX RPG II Specifications 


Output Specification (0) 


Column Allowable 


Number Values Explanation . 
17 Blank Does not advance before printing a line of output. 
0-3 Specifies the number of lines the printer will 


advance before printing a line of output. A value of 
zero allows overprinting. 


18 Blank Does not advance after printing a line of output. 


0-3 Specifies the number of lines the printer will 
advance after printing a line of output. A value of 
zero allows overprinting. 


e If you leave columns 17 through 20 blank for:a record specification 
line, VAX RPG II automatically spaces one line after printing the 
output line. 


e If there are no entries in columns 17 through 20 of an OR line, VAX 
RPG II uses the entries in a preceding line. 


e You cannot define the spacing and skipping for an AND line. 


Additional Information 


Because you can space up to only three lines before and after a line of 
output, you cannot specify more than five blank lines between output 
lines using entries in columns 17 and 18. Spacing to or past the overflow 
line causes VAX RPG II to set on the overflow indicator. 


15.8.9 Skip Before and Skip After 


Like the space before and space after columns, columns 19 through 22 
define the format of a printer output file. Unlike the entries in columns 17 
and 18, the entries in columns 19 and 20 can be used to specify more than 
five lines between lines and to specify a move to the next page. 


Use column 19 to specify the line number the printer must move to before 
printing a line of output. Use column 20 to specify the line number the 
printer must move to after printing a line of output. 
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Column Allowable 


Number Values Explanation . 
19,20 Blank Specifies no skipping before printing a line of 
output 
01-99 Causes the printer to move to the line number you 
specify before printing a line of output 
A0-A9 Causes the printer to move to the line number you 
specify 100 (A0) to 109 (A9) before printing a line 
of output 
BO-B2 Causes the printer to move to the line number you 
specify 110 (BO) to 112 (B2) before printing a line of 
output 
21,22 Blank Specifies no skipping after printing a line of output 
01-99 Causes the printer to move to the line number you 
specify after printing a line of output 
A0-A9 Causes the printer to move to the line number you 
specify 100 (AO) to 109 (A9) after printing a line of 
output 
BO-B2 Causes the printer to move to the line number you 
specify 110 (BO) to 112 (B2) after printing a line of 
output 


e Follow the same rules in Section 15.6.10 for AND and OR lines. 


e You can specify entries in all space and skip columns for a single 
program line. When you do, VAX RPG II executes the entries in the 
following order: skip before, space before, print the output line, skip 
after, and space after. 


e Specifying a skip entry past the overflow line causes VAX RPG II to 
set on the overflow indicator. See Chapter 9 for more information. 


e If you specify a skip entry to the same line number that the printer is 
currently on, no skipping takes place. 


e If you specify a skip entry to a line number less than the current line 
number, the printer advances to that line number on the next page. 


¢ The skip entry cannot exceed the entry for forms length (columns 18 
and 19 of the Line Counter specification). If there is no Line Counter 
specification, the skip entry cannot exceed the default, line 66. 
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15.8.10 Example 


I 7 
12345678901234567890123456789012345678901234567890123456789012545678901234567890 





The following example causes VAX RPG II to perform the following 
operations: 


Skip to line 27 and space two lines before printing the output line 
Skip to line 30 and space three lines after printing the output line 


Format (PB) 
| 


B 
| 
| 
| 
| 


| 
| 
| name | 
| 
| 


l+ Constant or edit word + 


Type (HDTE) . Edit codes , ONOCR - 
Fetch of] / Rel (FR) 1X ret eennnnnnn 
1 !Space | Y date edit YYiAad 
Itt Skip | Z zero suppress Y N 2 B K 
it | . te: NY 3CL 
lil | Indicators ank-after (B) NN 4D MO 
Hid of Field 

td 

Mt | 

11B 

4 


l 
End position 
| 
| 
| 
| 






cn a rs rr es | 





HREKRE H % x HRR-—--HX wens 


N 3 
PNAME 10 
WHOUSE 12 
COLOR 17 
WEIGHT 20 
QTY 24 


ZK-4503-85 


15.8.11 Indicators 


Use columns 24 and 25, 27 and 28, and 30 and 31 to enter previously 
assigned indicators to condition a line of output. 
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Column Allowable 


Number Values Explanation 

24-25 Blank Outputs the record or field. 

27-28 

30-31 

Indicator Outputs the record or field when the indicator you 
specify is on. 

25 * Repeat line. If the preceding record was output, this 
record will be output. If the preceding field was 
output, this field will be output. 

23,26,29 N Outputs the record or field when the indicator is 
off. N in column 23 conditions the indicator in 
columns 24 and 25. N in column 26 conditions the 
indicator in columns 27 and 28. N in column 29 
conditions the indicator in columns 30 and 31. 

Rules 


When you want an indicator to condition an entire record, enter the 
indicator on the line that specifies the type of record. When you want 
an indicator to condition a field, enter the indicator on the same line 
as the field name (columns 32 through 37). 


If you specify more than one indicator on a line, the indicators form 
an AND relationship. 


You can use overflow indicators on AND or OR lines; however, you 
can associate only one overflow indicator with a group of output 
indicators. If a line is to be considered an overflow line, the overflow 
indicator must appear on the main specification line or on an OR line. 


If you use an overflow indicator, it must be the same one assigned to 
the file on the File Description specification. 


You cannot use overflow indicators to condition exception output 
lines, but you can use them to condition fields in an exception record. 


Additional Information 


You can use one of the following indicators in columns 24 through 25, 27 
through 28, and 30 through 31: 


Record-identifying (01-99) 
Control-level (L1-L9) 
Last-record (LR) 
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* Matching-record (MR) 

e Halt (H1-H9) 

e External (U1-U8) 

¢ Overflow (OA-OG and OV) 
¢ K (KA-KZ and KO0-K9) 

e = First-page (1P) 

e Asterisk indicator (*) 


Note that VAX RPG II outputs those detail and heading lines conditioned 
by the first-page (1P) indicator, no indicator, or all negative indicators 

(N in columns 23, 26, or 29) before reading the first record from a file. 
Therefore, use the 1P indicator to condition only heading and detail output 
lines that do not depend on data from an input record. For a line with 
no indicators or all negative indicators that requires data from an input 
record, use a negative first-page indicator (N1P in columns 23 through 31) 
to prevent the line from being output before reading the first record. 


Because the 1P indicator is set off after the first detail-time output, it can 
be used only to condition heading and detail lines. 


If you use a control-level indicator with a total record and no overflow 
indicator, VAX RPG II writes the record when a control break occurs and 
after VAX RPG II processes the last record of a control group. If you use a 
control-level indicator with a detail record and no overflow indicator, VAX 
RPG II writes the record when a control break occurs and after it processes 
the first record of a new control group. If you use a control-level indicator 
with an overflow indicator, VAX RPG II writes the record when a control 
break occurs and passes the overflow line. 


If you have two or more output records that are to be output when the 
same conditions are set, you can specify the conditions on one Output 
specification record line and then use * in column 25 on following Output 
specification record lines of the same type. If you have two or more 
output fields that are to be output when the same conditions are set, you 
can specify the conditions on one Output specification field line and then 
use * in column 25 on following Output specification field lines. 
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Output Specification (0) 


The following example causes VAX RPG II to print the specified fields in 
the detail record if the 1P indicator is off: 


Type (HDTE) Edit codes , ONOCR - 
IFetch ofl / Rel (FR) | X tenn eenna 
| |Space | Y date edit YYiuiAad 
TIl Skip | Z zero suppress Y N 2 B K 
itt | NY 3 CL 
lll | = Indicators IBlank-after (B) N N 4 D M 

File oe | Field I!End position 

name Hid ot name |I! Format (PB) 

| Hid ost | 1th ot 
11B 111. 1+ Constant or edit word + 
1 | | 











0 | | 2 I 3 I 7 
12345678901234567890123456 7890123456 7890123456 7890123456 789012345678901234567890 


#% RRHRE HX % x RRR——— KE sees 
OOUTSOA D NiP 

0 N 3 

0 PNAME 10 

0 WHOUSE 12 

0 COLOR 17 

0 WEIGHT 20 

0 QTY 24 

0 PAGE 30 


ZK-4504-85 


15.8.12 Field Name 


Use columns 32 through 37 to specify the field name that identifies the 
item to be written to the output file. 


Column Allowable 


Number Values Explanation 
32-37 Blank Indicates the presence of a constant in columns 45 
through 70. 
Name Specifies the name of the item to print. The item 


can be a field name, table or array name, array 
element, or one of the following special words: 
PAGE, PAGE1-7, UDAY, UMONTH, UYEAR, 
UDATE, *IN, *INxx, and *PLACE. See Chapter 9 
for information on special words. 
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Output Specification (0) 


Rules 

e All field names must have been previously defined in an Input, 
Calculation, or Extension specification. 

¢ Left justify this entry. 


e You cannot enter a field name if you enter a constant in columns 45 
through 70. 


e If you enter a field name in columns 32 through 37, columns 7 
through 22 must be blank. 


e If you specify a nonindexed array name, the entire array is output. 


The following example specifies fields in the detail record: 





Type (HDTE) Edit codes , ONOCR - 
IFetch of! / Rel (FR) |X ttt ene nnen 
| |Space 1 Y date edit YYiad 
Ill Skip | Z zero suppress Y N 2 B K 
bt | | NY 3 CL 
tl | Indicators IBlank-after (B) N N 4 D M 
File to Field I!End position 
name Itt | | name |1| Format (PB) 
| | | i | 
Ol 11BAB A NxxNxxNxx | an 1+ Constant or edit word + 
) | 4 | 2 | 3 | ry | 5 | 6 | 7 | 
Ss LAE RR UA A Lea ICE el Tee 
#% HHERK HH HEE--—-#E or 
OOUT5OA D NiP 
0 N 3 
0 PNAME 10 
0 WHOUSE 12 
0 COLOR 17 
0 WEIGHT 20 
0 QTY 24 
0 PAGE 30 
; ZK-4505-85 


15.8.13 EXCPT Name 


When the record type is an exception record (indicated by an E in column 
15), a name can be placed in columns 32 through 37 of the record line. 
The EXCPT operation can specify the name assigned to a group of records 
to be written. The name is called an EXCPT name. 
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Output Specification (0) 


Column Allowable 
Number Values 


32-37. Blank 


Name 


Explanation 


Identifies exception output records to be written 
when an EXCPT opcode with a blank factor 2 is 
executed. 


Identifies exception output records to be written 
when an EXCPT opcode with the same name in 
factor 2 is executed. 


e An EXCPT name must follow the rules for field names. 


e An EXCPT name cannot be the same as a file name, field name, data 
structure name, array name, table name, label, or subroutine name. 


e A group of any number of output records can use the same EXCPT 
name, and the records do not have to be consecutive records. 


15.8.14 Edit Codes 


Use column 38 to specify an edit code. Edit codes allow you to perform a 
variety of editing functions on the data in a numeric output field. 


Column Allowable 
Number’ Values 


38 1 
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Explanation 


Prints a number with commas before every third. 
digit to the left of the decimal point, prints a zero 
balance, and suppresses signs and leading zeros. 


Prints a number with commas before every third 
digit to the left of the decimal point and suppresses 
a zero balance, signs, and leading zeros. 


Prints a number without commas, prints a zero 
balance, and suppresses signs and leading zeros. 


Prints a number without commas and suppresses a 
zero balance, signs, and leading zeros. 


Column Allowable 


Number 


Values 
A 


Output Specification (0) 


Explanation 


Prints a number with commas before every third 
digit to the left of the decimal point, prints a zero 
balance, uses CR to represent a negative sign, and 
suppresses leading zeros. 


Prints a number with commas before every third 
digit to the left of the decimal point, suppresses a 
zero balance, uses CR to represent a negative sign, 
and suppresses leading zeros. 


Prints a number without commas, prints a zero 
balance, uses CR to represent a negative sign, and 
suppresses leading zeros. 


Prints a number without commas, suppresses a zero 
balance, uses CR to represent a negative sign, and 
suppresses leading zeros. 


Prints a number with commas before every third 
digit to the left of the decimal point, prints a zero 
balance and prints a negative sign, and suppresses 
leading zeros. 


Prints a number with commas before every third 
digit to the left of the decimal point, suppresses a 
zero balance, prints a negative sign, and suppresses 
leading zeros. 


Prints a number without commas, prints a zero 
balance and a negative sign, and suppresses leading 
zeros. 


Prints a number without commas, suppresses a 
zero balance, prints a negative sign, and suppresses 
leading zeros. 


Performs no editing. 


Edits a date field using the format mm/dd/yyyy or 
the format dd/mm/yyyy, if you specify inverted 
print. If the first digit of a date field is zero, it is 
suppressed. 


Suppresses signs and leading zeros. 
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Output Specification (0) 


e If you use an edit code in column 38, columns 45 through 70 must be 


blank unless you specify an edit code modifier. 


e If you use an edit code to edit an array, VAX RPG II leaves two spaces 


to the left between the elements of the array. 


° You cannot use edit codes on numeric data in packed or binary format. 


Additional Information 


To prevent overlapping of the output fields, leave enough space for the 


characters so that the edit code will insert into the output field. 


Unedited numeric output fields with negative values are output with the. 
overpunched representation of the sign. For example, -1 will be output as 
J, -2 as K, and so on. See Chapter 14 for information on overpunched data 
format. Therefore, use an edit code or edit word to prevent the output of 
an overpunched representation of a sign. 


Table 15-6 shows the results of several edit code examples. 


Table 15-6: Edit Codes and Examples 


Edit 
Code 


none 


—- DAW F WN BB 


+12345.67 
1234567 

12,345.67 
12,345.67 
12345.67 
12345.67 
12,345.67 
12,345.67 
12345.67 
12345.67 
12,345.67 
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+1234567 
1234567 
1,234,567 
1,234,567 
1234567 
1234567 
1,234,567 
1,234,567 
1234567 
1234567 
1,234,567 


-1234,567 
123456P 
1,234,567 
1,234,567 
1234.567 
1234,567 
1,234.567CR 
1,234.567CR 
1234,567CR 
1234.567CR 
1,234.567- 


-1234567 
123456P 
1,234,567 
1,234,567 
1234567 
1234567 
1,234,567CR 
1,234,567CR 
1234567CR 
1234567CR 
1,234,567- 


Print 
Zero 
Balance 


yes 
yes 
no 
yes 
no 
yes 
no 
yes 
no 


yes 


Output Specification (0) 


Table 15-6 (Cont.): Edit Codes and Examples | 
Print 


Edit = Zero 
Code +12345.67 +1234567 -1234.567 -1234567 - Balance 
K 12,345.67 1,234,567 1,234.567- 1,234,567- no 

L 12345.67 1234567 1234.567- 1234567- yes 

M 12345.67 1234567 1234.567- 1234567- no 


15.8.15 Blank After 


Use column 39 to specify blank after, which causes VAX RPG II to 

reset the contents of the output field after writing it. VAX RPG II resets 
alphanumeric data with blanks and numeric data with zeros. Specifying 
blank after is especially useful when accumulating totals for each control 


group. 

Column Allowable 

Number Values Explanation | 

39 BL Causes VAX RPG II to reset the field after writing it 
Rules 


e This column must be blank for look-ahead fields, fields defined by 
an EXTRN operation, constants, and the following special words: 
UDATE, UDAY, UMONTH, UYEAR, and *PLACE. 


e If indicators condition the field you want to reset, the same indicators 
condition blank after. 


e If you specify blank after for a field that you want to write more than 
once, enter B in this column on the last line specifying output for that 
field. Otherwise, the field will be reset before being output again. 
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Output Specification (0) 


The following example specifies blank after for PAGE3: 





Type (HDTE) Edit codes , ONOCR - 
Fetch ofl / Rel (FR) |X j — seeeeeecerece= 
| 1Space | Y date edit YYdiAadJ 
lit Skip | Z zero suppress Y N 2 B K 
WW | NY 3 CL 
Hit Indicators IBlank-after (B) N N 4 D M 
File Hit ot Field {lEnd position 
name Wit | name II! Format (PB) 
| Itt | | I Hl I . 
0] |1BAB A NxxNxxNxx | 1 I+ Constant or edit word +. 
¢] I 1 | 2 3 | 4 | 5 | 6 | 7 | 
123456 7890123456 7890123456789012345678901234567890123456 7890123456 78901234567890 
HH RHEKH OK ¥ % H#ER—-—-—- HH antag 
OOUT5OA D NiP 
0 PAGES ZB 50 


ZK-4506-85 


15.8.16 End Position and Form 


Use columns 40 through 43 to indicate the location of an output field or 
constant. Enter the number of the position for the rightmost character. 
For example, if a field contains 20 characters and you specify 40 as the 
end position, the output might appear as follows: 
o |! 4 tt 2 4 38 t 4 J 
12345678901 2345678901 2345678901 2345678901 234567890 
South LyndeboroughNH 


The numbers above this example are for reference only; they do not 
appear in the output. 


Use K in column 42 if you are specifying a WORKSTN form name. 
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Output Specification (0) 


Column Allowable 


Number Values Explanation 

40-43 . 1-9999 Indicates the position of the rightmost character in 
an output field or constant 

42 K Indicates WORKSTN form name begins in column 
45. 

Rules 


If fields overlap, the last field you specify on the Output specification 
is the only field that is completely written. 


When specifying the end position for an array, use the rightmost 
position of the last element in the array. 


The end position must be less than or equal to the record length 
(columns 24 through 27 of the File Description specification) of the file 
to which the record belongs. 


Right justify this entry. 
Leading zeros can be omitted. 


Be sure to allow enough room for the number of characters in each output 
field and for the editing characters you specified using an edit code or edit 
word. 


The following example shows the rightmost character in each of these 
positions: 


First field is in character position 22 
Second field is in character position 40 
Third field is in character position 57 
Fourth field is in character position 75 
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Output Specification (0) 


Type (HDTE) Edit codes » ONOCR - 
IFetch of] / Rel (FR) |X jj — eeeeeeeeecen-- 
| |Space | ¥ date edit Heo A, ed 
111 Skip | Z zero suppress Y N 2 B K 
Hl | N Y 3 CL 
lt! | Indicators IBlank-after (B) N N 4 D NM 
File re Field |lEnd position 
name ti | | name II] Format (PB) 
| Iti | | | 1 
0| 11BAB A NxxNxxNxx | Itt 1+ Constant or edit word + 
| 






#% HRREK HX * KEH-—— HH aoe 

0 22 ‘EMPLOYEE NUMBER’ 

0 40 "EMPLOYEE NAME’ 

0 57 ‘REG EARNINGS’ 

0 75 OVER EARNINGS’ 

ZK-4507-85 
The output appears as follows: 
o ! 2 | 2 § 38 FJ 4 | 6B FT 6 | 7 J 


1234567890123456789012345678901 2345678901 2345678901 2345678901 2345678901234567890 
EMPLOYEE NUMBER EMPLOYEE NAME REG EARNINGS OVER EARNINGS 


The numbers above this example are for reference only; they do not 
appear in the output. 


15.8.17 Format 


If an output field contains numeric data, use column 44 to specify over- 
punched decimal, packed decimal, or binary data format. The packed 
decimal and binary formats conserve disk space. 


Column Allowable 
Number Values Explanation 


44 Blank Indicates that the field contains either alphanumeric 
characters or numeric data and is in overpunched 
decimal format 


Indicates that numeric data is in packed format 


B Indicates that numeric data is in binary format 
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Output Specification (0) 
Leave this entry blank for the output field if you specify an edit code, edit 
word, or the special word *PLACE. 


The following example specifies packed decimal format for the field QTYP 
and binary format for the field QTYB. 





Type (HDTE) Edit codes , ONOCR - 
IFetch ofl / Rel (FR) |X —— seeeeeecceen= 
| |Space | Y date edit YYiAad 
lit Skip | Z zero suppress Y N 2 B K 
lit | NY 3 CL 
1tl 4 Indicators IBlank-after (B) N N 4 D M 
File tlt | Field IlEnd position 
name Vit ft | name Ili | Format (PB) 
| it | | an | 
Ol | 1BAB A NxxNxxNxx | tI 1+ Constant or ah! word + 
i) | 2 | 3 | 4 ] 5 6 | 7 ] 
1234567890 123456789012345678001234557800 {234567090 1254557090 12345570901 234567090 
¥% HRKKH HX % HEK—--—-HE 
0 QTYP 32P 
0 QTYB 38B 


ZK-4508-85 


15.8.18 Edit Code Modifiers, Constants or Form Names, and Edit Words 


This section describes the options you can use to specify edit code modi- 
fiers, constants or form names, and edit words. 


15.8.18.1 Edit Code Modifiers 


Use columns 45 through 47 to specify edit code modifiers. Edit code 
modifiers can replace suppressed zeros to the left of the decimal point 
with asterisks (asterisk fill) or put a dollar sign ($) before the leftmost 
character (floating currency symbol). To specify these modifiers, enter the 
appropriate value described as follows. 
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Output Specification (0) 


Colann ‘Allowable 
N umber Values 
45-47 x! 


‘Symbol’ 


Explanation 


Replaces suppressed zeros to the left of the decimal 
point with asterisks (*). 


Places the currency symbol before the first signifi- 

cant digit in a numeric field. The currency symbol 
is the same symbol you define in column 18 of the 
Control specification. 


e Enclose edit code modifiers in apostrophes. 


e The floating currency symbol will not be printed for a zero balance 
when you use an edit code that suppresses a zero balance. 


e You cannot use the floating currency symbol or asterisk fill with 
simple (X, Y, and Z) edit codes. 


¢ You can specify a currency symbol before an asterisk fill by making 


the following entries: 


— Column 38 (edit code)—specify one of the combined edit codes. 


— Place a currency symbol constant one space before the beginning 
of the edited field on the Output specification. 


— Place an asterisk enclosed in apostrophes ('*') in columns 45 . 
through 47 on the same line as the edit code. 
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Output Specification (0) 


In the following example, if the field OTEARN, which is four digits long 
with two decimal positions, contains a zero balance, VAX RPG II prints a 
dollar sign before the asterisk fill. 





Type (HDTE) Edit codes , ONOCR - 
IFetch of] / Rel (FR) |X etme nena 
| |Space | Y date edit YYiAad 
111 Skip | Z zero suppress Y N 2 B K 
bit | I NY SCL 
Itt | = Indicators IBlank-after (B) NN 4 D M 
File Hitt Field |tEnd position 
name | name ||! Format (PB) 
| tt | | Ht 
0| | 1BAB A NxxNxxNxx| It] I+ Constant or edit word + 
0 | | 3 | 4 | 5 | 6 | 7 | 
12545678901234567890123456789012345678901234567890123456789012345678901234567890 
¥¥ HEHE H % HEH--—- 8% 
0 56 '$’ 
0 QTEARNi 61 ’%’ 
ZK-4509-85 
The output might appear as follows: 
o | 4 $$ 2 §| 38 | 4 | BB | 6 | 7 J 
12345678901234567890123456789012345678901 2345678901 23456789012345678901 234567890 


$¥% . ke 


VAX RPG II uses a dollar sign ($) as the currency symbol unless you 
specify another symbol in column 18 (currency symbol) of the Control 
specification. 


15.8.18.2 Constants or Form Names 


Use columns 45 through 70 to specify constants or WORKSTN form 
names. Place a double quotation mark (") in column 45 to specify a 
long character literal as a constant or form name. Constants are used to 
describe constant data in an output file. A WORKSTN form name requires 
a K in column 42. 
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Output Specification (0) 


Column Allowable 


Number Values Explanation . 
45 Double Causes VAX RPG II to print the characters within 
_ quotation single quotation marks on the line(s) that fol- 
(") low. All the rules for long character literals on 


Calculation specifications apply when used on 
Output specifications. See Section 15.7.5 for 
information on long character literals. 


45-70 Any Causes VAX RPG II to print the characters in 
character columns 45 through 70 for non-WORKSTN files. 
For WORKSTN files, the constant is used as a form 
name for a form to be displayed when column 42 
contains K. 


e Constants can contain up to 24 characters. 


¢ You must enclose constants within single quotation marks (‘). Use the 
keyboard apostrophe mark as the single quotation mark (for example, 
‘Subroutine’). The single quotation marks are not printed. 


e When using constants, leave columns 32 through 39 and column 44 
blank. 


¢ To include an apostrophe in a constant, you must use two consecutive 
apostrophes to represent one apostrophe (for example, ‘Subroutine’’s 
calculations’). 


15.8.18.3 Edit Words 


Use columns 45 through 70 to specify edit words. Edit words can be 
used to edit a numeric field. Edit words consist of three parts: the body, 
sign status, and expansion. The body is the portion of the edit word 
that provides space for the digits from the field to be edited. The body 
begins at the leftmost character position of the edit word and ends at the 
rightmost character position that i is to contain a digit from the field to be 
edited. 


The sign status is the portion of the edit word that is used to specify 
whether the field is positive or negative and to specify a constant, if 
needed. The sign status begins at the first character position to the right 
of the body and ends with CR or a negative sign (-). If you specify one of 
these symbols and the field is positive, blank spaces will be substituted in 
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Output Specification (0) 


the edited field. If you use CR or a negative sign and the field is negative, 
that symbol will be substituted in the edited field. 


If an edit word contains no CR or a negative sign to the right of the 
rightmost character that is to contain a digit, the edit word does not 
‘contain a sign status portion. 


The expansion consists of characters that will be printed regardless of the 
field’s sign status. The expansion begins immediately after the sign status 
(or body, if no sign status is used) and continues to the end of the edit 
word. 


The following table describes those characters you can use in the body of 
the edit word. . 


Column = Allowable 


Number Values Explanation 
45-70 Blank Indicates that the position in the edited field is 


to contain the digit from the same position in the 
numeric field. 


0 Indicates that the field is to be zero-suppressed. 
Place the zero in the rightmost position where 
zero-suppression is to stop. Each leading zero 
that appears to the left of and including the stop 
position of the numeric field is replaced with a 
blank space in the edited field. The first zero 
VAX RPG II encounters is the zero-suppression 
character. Any zero appearing after the first zero is 
treated like any other character. Zero-suppression 
begins at the leftmost position in the data and 
continues up through the stop position unless a 
nonzero digit is encountered to the left of the stop 
position. If VAX RPG II encounters a nonzero digit 
to the left of the stop position, zero-suppression 
stops at the position where the nonzero digit is 
encountered; that digit and all following digits to 
the right of the nonzero digit are printed. 
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Output Specification (0) 


Column Allowable 
Number Values 


* 


Symbol 


45-70 Decimal point 
or comma 


45-70 Any other 
character 
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Explanation 


Indicates that the field is to be edited using asterisk 
protection. Place the asterisk in the rightmost 
position where asterisk protection is to stop. Each 
leading zero that appears in the data to the left of 
and including the stop position is replaced with an 
asterisk. The first asterisk VAX RPG II encounters 
is the asterisk protection character. Any asterisk 
appearing after the first asterisk is treated like any 
other character. 


Indicates that the position in the edited field is to 
be a blank space. 


Prints the currency symbol. If the currency symbol 
appears in the body of the edit word immediately 
to the left of the zero suppression, it is printed 
immediately to the left of the first significant digit 
in the edited field. This type of currency symbol 
is called a floating currency symbol. A floating 
currency symbol cannot be used with asterisk 
protection. 


The currency symbol in the leftmost position of 
the edit word indicates that the dollar sign is to be 
printed in that exact position in the edited field. 
This type of currency symbol is called a fixed 
currency symbol. 


Indicates the exact position in the edited field where 
it is to be printed. If a decimal point or comma 
appears to the left of the most significant digit, 
VAX RPG II will replace it with a blank space or, if 
asterisk protection is specified, with an asterisk. 


Prints the characters in the edited fields, if the 
position is to the right of the most significant digit 
in the edited field. Any character to the left of 

the most significant digit in the edited field is 
replaced with a blank space or an asterisk if asterisk 
protection is specified. 


Output Specification (0) 


The following example shows both the floating and fixed currency symbol 









types: 
Type (HDTE) Edit codes , ONOCR - 
Fetch ofl / Rel (FR) |X tet eeeeecrcnn 
| |Space | Y date edit Y Y¥Yd41Ad 
111 Skip | Z zero suppress Y N 2 B K 
Vit | | NY) OE 
ltt | Indicators IBlank-after (B) N N 4 D M 
File th tI Field I!End position 
name itt | | name It! Format (PB) 
| Hd | | | Hy 
11B fll 1+ Constant or edit word + ) 
1 ] 





rT Mirra x HEK---HE Sau 
0 FLOAT 45 $0 =” 
0 FIXED 45 '$ : 
ZK-45 10-85 


In the example, if FLOAT and FIXED contain the characters 1234, the 
output appears as follows: 


0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 
Be Re EU eee pe rae rn ge tee aepat ane ee ee, emp e es 
1234 
$ 1234 


In the following example, VAX RPG II prints a comma before the fifth 
digit from the right and a decimal point before the rightmost two digits: 





Type (HDTE) Edit codes , ONOCR - 
IFetch of] / Rel (FR) |X ete eeacencee 
| |Space | Y date edit Y Y LA J 
111 Skip | Z zero suppress Y N 2 B K 
Ht | NY oe OL 
Ill | Indicators 1Blank-after (B) N N 4 D M 
File Hi lo Field !lEnd position 
name Hit ol name Ili Format (PB) 
| td | | 
Ol 1!1BAB A NxxNxxNxx|! Ht I+ Constant or edit word + 
3 | 4 | 5 | ff | 
1234567890123456789012345678901234567890123456 7890123456 789012345678901234567890 
[Ta HEHE # ce ine 
0 FLD G4 $ 5 gt 


ZK-45 11-85 
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In the preceding example, if FLD contains the data 123456, the output 
appears as follows: 





0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 
123456789012345678901 234567890 12345678901 2345678901 23456789012345678901234567890 
$1,234.56 
In the preceding example, if FLD contains the data 56, the output appears 
as follows: 
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 
12345678901234567890123456789012345678901 2345678901 2345678901 2345678901234567890 
56 
Type (HDTE) Edit codes , ONOCR - 
IFetch ofl / Rel (FR) |X treet eeenecnn 
| Space | Y date edit YYiad 
Ht Skip | Z zero suppress Y N 2 B K 
Vit | | NY 3 CL 
ltl | Indicators IBlank-after (B) N N 4 D M 
File | Field I!End position 
name Htet | name II! Format (PB) 
| Wt tf | Wt 
Ol 1 |BAB A NxxNxxNXxx | 111 1+ Constant or edit word + 
I 2 | 3 | 4 | a) a 5) | 7 | 
12345678901234567890123456 78901234567890123456 7890123456 7890123456 7890123456 7890 
xe HEH * HER---4H eee 
0 FLD 45 '$ , . &BALANCE’ 


ZK-45 12-85 


In the preceding example, if FLD contains the data 123456, the output 
appears as follows: 


0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 


123456789012345678901234567800123456789012345678901 2345678901 2345678901234567890 
$1,234.56 BALANCE 
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File 
name 





#% 
0 


Output Specification (0) 


The following table describes those characters you can use in the status 
portion of the edit word. 


Column Allowable 


Number Values Explanation 
45-70 CR or - Indicates that the specified symbol (CR or a negative 


sign (-)) is to be printed in the edited field if the 
data is negative. If the edited field is positive, the 
specified symbol is replaced by blanks. 


Any Prints the specified character(s) in the edited field 
character if the data is negative; otherwise the character 
is replaced by a blank. If an ampersand (&) is 
specified, it will be replaced by a blank space. 


Type (HDTE) Edit codes , ONOCR - 
Fetch ofl / Rel (FR) |X tte enn nena 
| 1Space | Y date edit Y¥ £ AJ 
| Skip | Z zero suppress Y N 2 B K 
NY 3 CL 

Indicators ank-after (B) N N 4 D M 


| name Format (PB) 
| 


| | 
| 1B 
1 | Field I! 
I lI 
| 1 
HI 


] 

End position 
| 

| 

| I+ Constant or edit word + 
| 





| | I 3 4 | | 6 | 7 | 
1234567890123456 7890123456 7890123456 7890123456 7890123456 7890123456 78901234567890 
‘KHER XX ¥ HRR—--—HX aac 
FLD 45 7¢ , » &CRRBALANCE’ 
ZK-4513-85 


In the preceding example, if FLD contains the data -123456, the output 
appears as follows: 
a ree ene Cee eee ae! |S, ae ae  - 


12345678901234567890123456789012345678901234567890123456789012345678901234567890 
$1,234.56 CR BALANCE 
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Output Specification (0) 


Leave column 38 (edit code) blank. 


You must complete columns 32 through 37 (field name) and columns 
40 through 43 (end position). 


Edit words can be used only with overpunched numeric data. 
(Column 44 (data format) must be blank.) 


Edit words can be up to 24 characters long. 
Enclose edit words in apostrophes. 


The number of replaceable characters in an edit word must be greater 
than or equal to the number of digits in the numeric field. 


If you want all leading zeros to be printed, increase the edit word by 
one position to the left of the leftmost digit and place a zero in that 
position. 

When the floating currency symbol is used, the sum of the number 
of blanks and the zero-suppression in the edit word must be equal 
to or greater than the number of digits in the edited field. A floating 
currency symbol is not counted as a digit position. 


Any zeros or asterisks following the leftmost zero suppression code or 
asterisk protection are treated as constants and are not replaced with 
digits. 
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Chapter 16 
Operation Codes 


VAX RPG II operation codes perform calculations on the operands you 
specify in Calculation specifications. In the following sections, operation 
codes are grouped by function and discussed individually in detail. A 
summary of all operation codes is provided at the end of this chapter, in 
Table 16-1. 


16.1 Arithmetic Operation Codes 


This section describes arithmetic operation codes which perform a variety 
of functions, ranging from adding two operands to taking the square root 
of an operand. 


When you use arithmetic operation codes, you must consider the following 
restrictions and default characteristics: 


e You can use arithmetic operation codes only with numeric fields and 
numeric literals. 

e VAX RPG II aligns the operands according to their decimal points 
before performing any arithmetic operation. VAX RPG II aligns the 
result on the decimal point in the result field, which could cause 
truncation. 

e The contents of factor 1 and factor 2 do not change during an arith- 
metic operation unless the same field is used as the result field. 


e Any existing data in the result field is replaced with the result of the 
current operation. 

¢ Make sure the field length of the result field is large enough to hold 
the result of the operation. Otherwise, the result of the operation is 
truncated before being placed in the result field. 
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16-2 Operation Codes 


You can specify half adjust (column 53 of the Calculation specification) 
for any arithmetic operation except an MVR operation and the DIV 
operation immediately preceding it. 


You can specify the same field for factor 1 and factor 2 and/or the 
result field, if desired. 


You can leave factor 1 blank. If you do, the statement is treated as if 
the result field were specified in factor 1. 


You can specify an entire array as an operand of the ADD, SUB, 
Z-ADD, Z-SUB, MULT, DIV, and SQRT operation codes. See 
Chapter 11 for information on using arrays in calculations. 


No field in an arithmetic operation can be longer than 15 digits. 

VAX RPG II performs all arithmetic operations algebraically. 

The result of all arithmetic operations is signed. The sign of the result 

of an arithmetic operation depends on the operation. 

Addition: 

— If factor 1 and factor 2 have like signs, the result field has the 
same sign. 

— If factor 1 and factor 2 have unlike signs, the result field uses the 
sign of the factor with the largest absolute value. 

Subtraction: 

— Change the sign of factor 2 (positive to negative or negative to 
positive) and use the same rules as for addition. 

Multiplication: 


— If factor 1 and factor 2 have like signs, the gn of the result field 
is positive. 


— If factor 1 and factor 2 have unlike signs, the sign of the result 
field is negative. 

Division: 

— If factor 1 and factor 2 have like signs, the sign of the result field 
is positive. | 

— If factor 1 and factor 2 have unlike signs, the sign of the result 
field is negative. 

— The sign of the remainder is the same as the sign of factor 1. 


16.1.1 


16.1.2 


16.1.3 


16.1.4 


16.1.5 


ADD Operation 


The ADD operation adds the contents of factor 1 to factor 2 and puts the 
sum in the result field. If you leave factor 1 blank, the statement is treated 
as if the result field were specified in factor 1. 


Z-ADD Operation 
The Z-ADD operation assigns the value of factor 2 to the result field. 

SUB Operation 
The SUB operation subtracts the contents of factor 2 from the contents of 
factor 1 and puts the difference in the result field. If you leave factor 1 
blank, the statement is treated as if the result field were specified in 
factor 1. 

Z-SUB Operation 
The Z-SUB operation multiplies the contents of factor 2 by -1 and puts the 
result in the result field. 

MULT Operation 


The MULT operation multiplies factor 1 by factor 2 and puts the product 
in the result field. If you leave factor 1 blank, the statement is treated as if 
the result field were specified in factor 1. 


The field length of the result field for a MULT operation should equal the 
sum of the field lengths of factor 1 and factor 2. This procedure ensures 
that the result field can contain the maximum value. 
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16.1.6 DIV Operation 


The DIV operation divides factor 1 by factor 2 and puts the quotient in the 
result field. If you leave factor 1 blank, the statement is treated as if the 
result field were specified in factor 1. 


Factor 2 cannot be zero. If it is, a run-time error occurs. The remainder 
is lost unless you use the MVR operation immediately following the DIV 
operation. 


16.1.7 MVR Operation 


MVR moves the remainder from the division operation on the preceding 
line to the result field. The decimal position of the remainder is the greater 
of either of the following: 


1. The number of decimal positions specified for factor 1 


2. The sum of the number of decimal positions specified for factor 2 and 
the result field of the preceding DIV operation 


The sign of the remainder is the same as the sign of factor 1 in the DIV 
operation. 


Because DIV and MVR operation codes work together, use the same 
indicators to condition both operations. 


You cannot specify half adjust (column 53 of the Calculation specification) 
for a DIV operation immediately followed by an MVR operation. 


You cannot use the MVR operation if, in the immediately preceding DIV 
operation, you specified an entire array (nonindexed) in the result field. 


16.1.8 SORT Operation 


The SQRT operation calculates the square root of factor 2, half adjusts 
the value, and puts the result into the result field. The result of a SQRT 
operation is always half adjusted. Factor 2 cannot be a negative number. 
If the field contains a negative number, a run-time error occurs. If you use 
a negative numeric literal, a compile-time error occurs. 
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16.1.9 XFOOT Operation 


The XFOOT operation puts the sum of all the array elements into the 
result field. Factor 2 contains the name of the array. If the result field 
contains an array element of the array you specify in factor 2, the original 
value of the element is used during the operation. 


You can half adjust the contents of the result field. 


The following example demonstrates the use of arithmetic operation codes: 


Field length 
I 


Control level 


| 

| Indicators 
| 

1 | Factor 
1 | | 

Cl NxxNxxNxx | 

0 | 1 





HE % x 
12 ¢ PURCH 
{13 ¢ AMTFIN 
14 C¢ FINCHG 
15 ¢ AMTDUE 
16 C 
17 ¢ 
18 ¢ 
30 C 
sic 
46C 


Operation 
| 


| Factor 
| 2 
| | 


# * 

SUB DWNPAY 
MULT .18 
ADD AMTFIN 
DIV 13 

MVR 
Z-ADDS. 00 
ADD AMTDUE 


Z~SUB10,00 
Z-ADD6. 99 


SQRT FINCHG 


| 

| 

i 
Result! 
field | 
i; | 
4 


| 2 I 3 7 | 
123466 789012345678901234567890123456789012345678901234567890125456 7890125456 7890 





Decimal positions 
IHalf adjust (H) 
1 


| [Resulting 
| | indicators 
li+ - 0 
HI> c= 
5 | 


+~ Comments --+ 
| 


% ~ = F—-KRE BRR 


AMTFIN 
FINCHG 
AMTDUE 
MTHPAY 
REMAIN 
TOTDUE 
TOTDUE 


EARPAY 
LATCHG 


TAX 


62H 
62H 


42H 
32H 


42H 
2K-4514-85 
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For the preceding example, the following table lists the data in each 
operand before and after the operation. 


Program line Factor 1 Operation Factor 2 Result field 
2 ©) («12299'ti‘C ;*“‘ ‘(;‘“‘<dLOCDOCUOD 
13 1200.00 * .18 216.00 

14 216.00 + 1200.00 1416.00 

15 1416.00 7 13 108.92 

16 MVR 0.04 

18 ADD 1416.00 1421.00 

30 Z-SUB 10.00 -10.00 

31 Z-ADD 6.99 6.99 

46 SQRT 216.00 14.70 


16.2 Move Operation Codes 


MOVE operation codes transfer data from a field in factor 2 to the result 
field. Although the contents of factor 2 remain unchanged, you can move 
all or part of the field in factor 2 and either retain or change the format of 
the data as you move it. 


In move operations, VAX RPG II ignores the decimal positions of numeric 
fields. You cannot use resulting indicators with any move operation. 


16.2.1 MOVE Operation 


The MOVE operation transfers the contents of factor 2 to the result 

field. The transfer begins with the rightmost character of factor 2 to the 
rightmost character of the result field. If the result field is not large enough 
to accommodate factor 2, VAX RPG II moves only enough characters 
(beginning with the rightmost character) to fill the result field. If the field 
length of the result field is longer than factor 2, the leftmost characters of 
the result field are not changed. If VAX RPG II transfers numeric data, the 
sign of the result field is the same as the sign of factor 2. 
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When you move an alphanumeric field to a numeric field, VAX RPG II 
converts the digit portion of each character to its corresponding numeric 
character and then moves the numeric character to the result field. VAX 
RPG II converts the zone portion of the rightmost character to its corre- 
sponding sign and then moves the sign to the rightmost character position 
of the numeric result field, where it becomes the sign of that field. 


16.2.2 MOVEA Operation 


The MOVEA operation transfers data from factor 2 to the result field. 
Either factor 2 or the result field must contain an array or array element. 
If you specify an array element, it specifies the beginning position of the 
transfer. Both factor 2 and the result field must be character fields or 
arrays. 


You can move several contiguous array elements to a single field or move 
a single field to several contiguous array elements. 


Movement of data from factor 2 to the result field begins with one of the 
following: 


1. The leftmost character of the first element in the array, if you specify 
an entire array (nonindexed) 


2. The leftmost character of the element you specify, if you specify an 
array element (indexed) 


3. The leftmost character of the field, if you specify a field 


The length of factor 2 and the result field is determined by the length of 
one of the following: 


1. An entire array, if you specify an entire array (nonindexed) 


2. An array from the specified array element to the end of the array, if 
you specify an array element (indexed) 


3. A field, if you specify a field 


If the field length of factor 2 is greater than the field length of the result 
field, VAX RPG II does not move the excess rightmost characters. If the 
field length of the result field is greater than the field length of factor 2, 
the rightmost characters in the result field remain unchanged. 


Array element boundaries are ignored in a MOVEA operation. Therefore, 
movement of data into the result field can end in the middle of an array 
element. 
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16.2.3 MOVEL Operation 


The MOVEL operation transfers the contents of factor 2 to the result field. 
The transfer begins with the leftmost character of factor 2 to the leftmost 
character of the result field. 


When the field length of factor 2 is equal to the field length of the result 
field, the following rules apply: 


If factor 2 contains alphanumeric data and the result field is alphanu- 
meric, VAX RPG II moves characters without changing them. 


If factor 2 contains numeric data and the result field is numeric, the 
sign of factor 2 becomes the sign of the result field. 


If factor 2 contains numeric data and the result field is alphanumeric, 
VAX RPG II moves the sign in the rightmost character position. 


If factor 2 contains alphanumeric data and the result field is numeric, 
each character is converted to its corresponding numeric digit and 
moved to the result field. The zone portion of the rightmost character 
in factor 2 is used to determine the sign of the result field. 


When the field length of factor 2 is longer than the field length of the 
result field, the following rules apply: 


If factor 2 contains alphanumeric data and the result field is alphanu- 
meric, VAX RPG II moves only the number of characters needed to fill 
the result field. 


If factor 2 contains numeric data and the result field is numeric, the 
sign of factor 2 becomes the sign of the result field. 


If factor 2 contains numeric data and the result field is alphanumeric, 
the result field contains only numeric data; that is, the sign of factor 2 
is not used. 


If factor 2 contains alphanumeric data and the result field is numeric, 
the leftmost characters of factor 2 are converted to the corresponding 
numeric digits and moved to the result field. The zone portion of the 
rightmost character in factor 2 is used to determine the sign of the 
result field. 


When the field length of factor 2 is shorter than the field length of the 
result field, the following rules apply: 
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If factor 2 contains either numeric or alphanumeric data and the result 
field is numeric, VAX RPG II moves the digits of numeric fields or 
the corresponding numeric digits of factor 2, if alphanumeric, into the 


leftmost character positions of the result field. The sign of the result 
field remains unchanged. 


e If factor 2 contains either numeric or alphanumeric data and the result 
field is alphanumeric, VAX RPG II moves the data into the result 
field beginning with the leftmost character position. The rightmost 
character positions in the result field remain unchanged. 


16.2.4 Example 


In the following example, the preexecution-time array ARR1 is read from 
the input file ARRFILE and is copied to the execution-time array DUPARR. 
The array is modified by moving the input field INPFLD to the second 
and third elements of the array. In addition, the field MYREC consists of 
the first element in ARR1 and the last three characters of the third element 
in ARR1. 


0 | i I 2 | 3 | 4 I 5 I 6 | 7 
1234567890123456789012345678901234567890123456 7890123456 789012345678901 234567890 





E ARRFILE : ARR 6 6 § 
E DUPARR 6 5 
TARRFILE AA O01 
4 10 INPFLD 
MOVEAARR1 DUPARR 


MOVEAINPFLD ARR1,2 
MOVE ARRi,3 MYREC 868 
MOVELARR(, 1 MYREC 


OIAIMIeH 


ZK-45 15-85 


For the preceding example, the input file (ARR1) contains the following 


data: 

Field Data 
ARR1,1 12345 
ARR1,2 67890 
ARR1,3 ZZZZZ 
ARR1,4 ZZZZZ 
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Field Data 


ARR15 ZZZZZ 
ARRI1,6 ZZZZZ 
INPFLD ABCDEFGHIJ 


After executing the program, the fields would contain the following data: 


MYREC = 12345HTJ 


ARR1,1 = 12345 
ARR1,2 = ABCDE 
ARR1,3 = FGHIJ 
ARR1,4 = 2Z2ZZ 
ARR1,5 = ZZ2ZZZ 
ARR1,6 = ZZZZZ 
DUPARR = 1234567890ZZ2ZZZZ2Z2ZZZ2ZZZZZZ2ZZ 


16.3 SET Operation Codes 


SET operation codes (SETON and SETOF) set indicators on and off. They 
affect only those indicators in columns 54 through 59. 


If you use SET operation codes to set control-level indicators on and off, 
they do not affect lower-level control-level indicators. 


16.3.1 SETON Operation 


The SETON operation sets on the indicators you specify in columns 54 
and 55, 56 and 57, and 58 and 59. You cannot set the first-page (1P) or 
matching-record (MR) indicators on. 


If you use SETON to set the LR indicator on at total time, processing stops 
after VAX RPG II finishes total-time output operations. 


If you use SETON to set the LR indicator on at detail time, processing 
stops after VAX RPG II finishes the next total-time output operation. 


If you use SETON to set halt indicators on and they are not set off before 
VAX RPG II finishes detail-time output operations, processing stops. 
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16.3.2 SETOF Operation 


The SETOF operation sets off the indicators you specify in columns 54 
and 55, 56 and 57, and 58 and 59. You cannot set the first-page (1P) or 
matching-record (MR) indicators off. 


In the following example: 


° The SETON operation sets indicators 11 and 22 on. 
e The SETOF operation sets indicator 33 off. 


Field length 
Control level | Decimal positions 
IHalf adjust (H) 





| 
| Indicators Operation 1 od 
1 | | | {Resulting 
1 | Factor | Factor Result! tlindicators 
lt | | 2 field | Jl+- 0 . 
Cl NoxoxNogachcoc I oe fie ts gles 1. Ut < = +- Comments --+ | 
i) | 4 | 2 3 | 4 | 5 | 6 | 7 | 
ELT UTC CER TEE De cA eR EE LT Lr 
#% % % P H--KRE HH * 
¢ SETON 1122 
C SETOF 33 
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16.4 Subroutine Operation Codes 


Subroutine operation codes are used to identify and execute subroutines. 
A subroutine is a group of Calculation specifications that you can execute 
more than once in a single program cycle using the ESXR operation code. 


You can specify SR in columns 7 and 8 to indicate that the specification 
is part of a subroutine, although this is optional. You cannot use control- 
level indicators in columns 7 and 8 of a subroutine. However, you can use 
any indicator in columns 9 through 17. Also, you can use AN and OR in 
columns 7 and 8 to specify a relationship between two program lines. 


You can use a maximum of 254 subroutines in a program. Subroutines 
must be placed after all other calculations. Subroutines cannot be nested 
or recursive. However, you can use the EXSR operation to call one 
subroutine from another. 
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16.4.1 BEGSR Operation 


The BEGSR operation indicates the beginning of a subroutine and must be 
the first specification in a subroutine. Factor 1 contains the name of the 
subroutine. All other columns in the same specification must be left blank 
except for an optional SR in columns 7 and 8. 


16.4.2 ENDSR Operation 


The ENDSR operation indicates the end of a subroutine and must be the 
last specification in a subroutine. Factor 1 can contain a label for a GOTO 
operation within the subroutine. All other columns in this specification 
must be blank, except an optional SR in columns 7 and 8. 


After the program reaches the ENDSR operation, it returns program 
control to the specification immediately following the EXSR operation 
code that invoked the subroutine. 


16.4.3 EXSR Operation 


The EXSR operation executes a subroutine. Factor 2 contains the name 
of the subroutine. It must be the same name you used in factor 1 of the 
BEGSR operation. You can use control-level and conditioning indicators 
to condition EXSR. 


After the program performs the operations in the subroutine, control 
branches to the specification immediately following EXSR. 
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16.4.4 Example 


In the following example, line 11 causes VAX RPG II to execute the 
subroutine SUB1. The subroutine consists of lines 22 through 24. 


Field length 
Control level | Decimal positions 
| IHalf adjust (H) 
I] 





| 
| Indicators Operation | 
| | [Resulting 
1 | Factor | Factor Result! Itlindicators 
1 | 4 | 2 field | Il+- 0 
Cl ONxxNxxNxx | | I | | Jl> < = +- Comments --+ . 
1 | 2 | 4 | 5 | 6 | 7 J 
AE SLCHI EAE AL ES ee RE lee CE 
% H--KHH HH * 
4ic 02 EXgR Sup! 
2e CSR SUB1 BEGSR 
235 CSR 02 HOURS MULT RATE DAYPAY 52H 
24 CSR ENDSR 
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16.5 BIT Operation Codes 


The BIT operation codes set and test bits. You must use one-character 
alphanumeric fields in factor 2 and the result field. 


16.5.1 BITON Operation 


The BITON operation sets on the bits you specify in factor 2 in the result 
field, replacing the value in the result field. Factor 2 contains the source of 
bits in bit numbers or a field name. 


You can set on bit numbers 0 through 7. Zero is the leftmost bit. You 
must enclose the bit number in apostrophes. For example, to set bits 1, 2, 
and 3 on, enter ‘123’ in factor 2. You cannot specify a bit number more 
than once. 
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The field name is a one-character alphanumeric field, table, or array 
element. The bits that are on in the field name are set on in the result 
field. If you specify an array element, each array element must be a 
one-character field. 


You can use indicators in columns 7 through 17, but the following 
columns must be left blank: 


e Columns 18 through 27 (factor 1) 

¢ Column 52 (decimal positions) 

¢ Column 53 (half adjust) 

¢ Columns 54 through 59 (resulting indicators) 


16.5.2 BITOF Operation 


The BITOF operation sets off the bits you specify in factor 2 in the result 
field, replacing the value in the result field. To specify operands for 
BITOF, follow the same guidelines as for BITON. 


16.5.3 TESTB Operation 


The TESTB operation compares the bits in factor 2 with the corresponding 
bits in the result field. Factor 2 can contain bit numbers or a one-character 
alphanumeric field. Bit numbers and one-character alphanumeric fields 
follow the same rules as those for BITON and BITOF. 


Indicators in columns 54 through 59 reflect the status of the bits in the 
result field; therefore, you must assign at least one resulting indicator. You 
can set up to three resulting indicators, but no more than two resulting 
indicators can be identical. 


If factor 2 is a field in which all bits are off, no resulting indicator is set 
on; otherwise, indicators in columns 54 through 59 indicate the result of 
the comparison as follows: 


¢ VAX RPG II sets the indicator in columns 54 and 55 on, if all bits 
specified in factor 2 in the result field are off. 


e VAX RPG II sets the indicator in columns 56 and 57 on, if some bits 
specified in factor 2 in the result field are on and some are off. 


e VAX RPG II sets the indicator in columns 58 and 59 on, if all bits 
specified in factor 2 in the result field are on. 
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16.5.4 Example 


Control level 


You can use indicators in columns 7 through 17, but the following 
columns must be left blank: 


Columns 18 through 27 (factor 1) 
Column 52 (decimal positions) 
Column 53 (half adjust) 


In the following example: 


Line 34 sets on the bits 1, 2, and 3 in the result field FLD1. 


Line 35 tests the bits 1, 2, and 3 in the result field FLD1. If all the 
bits are on, indicator 11 is set on. If one or more of the bits are off, 


indicator 11 is set off. 


Line 36 sets off the bits 4, 5, and 6 in the result field FLD2. 


Line 37 tests the bits 4, 5, and 6 in the result field FLD2. If all the 
bits are off, indicator 22 is set on. If one or more of the bits are on, 


indicator 22 is set off. 


| 
| Indicators Operation | 
1 | | | 
1 | Factor | Factor Result! 
1 | i | 2 field | 


Cl NxxNxxNxx | | | | | 
| | ‘ 


Field length 
| 


Decimal positions 
IHalf adjust ¢H) 
II 


| 1Resulting 
llindicators 
[1+ - 0 
1{> < = +- Comments --+ 
vi | 





| 2 | 3 | 4 | a) | 6 
Ege gS Ea a ee TER ace TE Ee 


HH X 
34 C€ 
35 ¢ 
36 C 
37 C¢ 


H-—-HEE HHH 


BITON’ 123’ FLD 
TESTB’ 123’ FLD4 
BITOF’ 456’ FLD2 
TESTB’ 456’ FLD2 


it 


ee 
Z2K-45 18-85 
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16.6 COMP Operation Code 


The COMP operation tests fields for certain conditions. Based on the 
result of the comparison, you can assign resulting indicators to condition 
calculation and output operations. 


The COMP operation compares the contents of factor 1 to the contents of 
factor 2. An indicator in columns 54 through 59 indicates the result of the 
comparison as follows: 


If factor 1 is greater than factor 2, VAX RPG II sets on the indicator in 
columns 54 and 55. 


If factor 1 is less than factor 2, VAX RPG II sets on the indicator in 
columns 56 and 57. 


If factor 1 is equal to factor 2, VAX RPG II sets on the indicator in 
columns 58 and 59. 


You must specify at least one resulting indicator. The result field must be 
left blank. 


When using the COMP operation, consider the following restrictions and 
default characteristics: 
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If you compare numeric fields, the fields are aligned at their implied 
decimal point. Fields are filled with zeros to the left and right of the 
decimal point until both fields are equal in length. For example, if you 
compare 1234.56 to 1.2, VAX RPG II fills the second field (1.2) with 
zeros (0001.20) until both fields are equal in length. 


If you compare alphanumeric fields of unequal lengths, the fields are 
aligned at the leftmost character. Shorter fields are filled with blanks 
until the two fields are equal in length. 


VAX RPG II compares numeric fields algebraically. 
Positive numeric fields are greater than negative numeric fields. 


If you have specified an alternate collating sequence, VAX RPG II 
translates character fields to the alternate collating sequence before 
comparing them. 


You cannot compare an alphanumeric field to a numeric field. 
You cannot compare entire arrays (nonindexed). 


In the following example, if the contents of the field CODE are greater 
than 1, VAX RPG II sets on indicator 11 and sets off indicators 22 and 33. 
If the contents of CODE are less than 1, VAX RPG II sets on indicator 22 
and sets off indicators 11 and 33. If CODE is equal to 1, VAX RPG II sets 
on indicator 33 and sets off indicators 11 and 22. 


| Field length 
Control level | Decimal positions 
IHalf adjust (H) 





: | 
| Indicators Operation 1 Jl 
| | | |lResulting 
1 | Factor | Factor Result! tflindicators 
i | | | 2 field | Il+- 0 
Cl NxxNxxNxx | | | | 1 dls £ = +- Comments --+ 
fy) | Fs I 3 4 ] 5 | 6 | F | 
1234567890123456789012345678901234567890123456 7890123456 7890125456 78901254567890 
RK % % % % % RO“ OH KF 
¢C CODE COMP 71’ 112233 
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16.7. Input and Output Operation Codes 


You can use the following operation codes to alter the normal input and 
output sequence, enabling the program to read and write records during 
calculations. 


16.7.1 CHAIN Operation 


The CHAIN operation reads a record from a file during calculations and 
places the contents of the record into the fields you specify on the Input 
specification. You can read records randomly from a sequential, direct, or 
indexed file. 


e If you want to read a record from a sequential or direct file, factor 1 
must contain the relative record number of that record. If you want to 
read a record from an indexed file, factor 1 must contain a field name 
or a literal that is the key of that record. The field length of the field 
or literal specified in factor 1 must be the same as the field length of 
the key. 
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¢ Factor 2 contains the name of the file from which the record is read. 
This file must be the same file you describe with a C or an F in column 
16 (type) in the File Description specification. 

e You can use any indicator in columns 7 through 17, but columns 43 
through 53 and 56 and 57 must be left blank. If you condition the 
chained or full-procedural file with an external indicator, use the same 
indicator to condition the CHAIN operation. 


e You can specify an indicator in columns 54 and 55 to verify the 

CHAIN operation. If VAX RPG II cannot locate the record, it sets 

on the indicator in these columns. If you do not use an indicator 

in columns 54 and 55, and VAX RPG II cannot locate the record, a 
run-time error occurs. If VAX RPG II cannot locate the record, you 
can add a record to the chained file (if you use a resulting indicator to 
indicate that a record has not been found), but you cannot update the 

~ record. 


e¢ You can specify on a CHAIN operation that if a record is locked, to 

set on an indicator. Enter the indicator for a locked record in columns 
58 and 59 of a Calculation specification. If you specify an indicator in 
columns 58 and 59, the program will not wait for the record to become 
unlocked before proceeding and will set on the indicator to show that 
the requested record is locked. If you do not specify the indicator, the 
program will wait until any record lock is released before proceeding. 
This indicator is allowed only on CHAIN operations to files that are 
marked as SHARE (S or R in column 68 on File specifications). The 
file cannot be an output file. Note that if another program has locked 
a record for update, but uses the file sharing option R, then a CHAIN 
operation that accesses that record will be successful; no lock will be 
seen and an indicator in columns 58 and 59 will be set off. 


e If you chain to a file with packed keys, the field in factor 1 of the 
CHAIN operation must be numeric and have the same number of 
digits as the key in the chained or full-procedural file. Packed key 
fields can be up to eight bytes long. 


e If you use one or more chained or full-procedural files during the same 
program cycle and the previous CHAIN operation was successful, any 
record-identifying indicators you use remain on throughout the cycle. 
If you use a chained file more than once during the same program 
cycle, only the last record processed can be updated during output, 
unless you specify exception output for each CHAIN operation. 


e The CHAIN operation is also used to load a direct file (a chained 
output file). Use the CHAIN operation to position the file to the 
record you want to add to the file. 


See Chapter 8 for information on processing files. 


16-18 Operation Codes 


In the following example: 


e Line 33 retrieves the record from the input file FILE1 with the relative 
record number specified in the field RECNO. If the record is not 
found, VAX RPG II sets on indicator 11. If the record is found, VAX 
RPG II sets off indicator 11. 

e Line 34 branches to a TAG operation to terminate the program if the 
previous CHAIN operation causes a record-not-found error. 

e Line 55 retrieves the record with the key 761 from the indexed file 
FILE2. If a record with a key of 761 does not exist, VAX RPG II sets 
on indicator 22. If a record with a key of 761 does exist, VAX RPG II 
sets off indicator 22. 
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16.7.2 DSPLY Operation 


The DSPLY operation allows you to display on line up to 511 characters 
at run time. VAX RPG II can do the following: 


e Display up to 511 characters from a field without suspending program 
execution. Factor 1 names the field to display. 


e Display the number of characters up to one less than your screen 
width from the result field. The program suspends execution after 
displaying the result field. The cursor is positioned at the next line 
where you can enter a new value for the result field from the terminal. 
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When entering a new value for the result field, terminate the input by 
pressing either the RETURN key or the TAB key. If you press only a 
RETURN key or a TAB key for the new value of the result field, the data 
in the result field remains the same. 


When using the DSPLY operation, observe the following restrictions and 
default characteristics: 


e You cannot change the contents of a literal; therefore, do not specify a 
literal in the result field. 


¢ The maximum length of the result field is one character less than the 
screen width. 


When entering data for the result field, consider the following 

characteristics: 

e You do not need to fill numeric data with leading zeros. 

e Numeric data is aligned on the decimal point when entered into the 
result field. 

e Alphanumeric data is left-justified when entered into the result field. 


e If you enter no characters and press either the RETURN key or the 
TAB key, the value in the result field remains unchanged. 


16.7.3 Example 


In the following example, if the data in NUMBER is greater than 100.0, 
the number will be displayed on the screen and will be followed on the 
next line by the current value of RESNO. Then, you can enter a new value 
for RESNO and press the RETURN key. 
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16.7.4 EXCPT Operation 


The EXCPT operation allows you to write a variable number of records 
during detail-time or total-time calculations or to display a form with a 
WORKSTN file. To do this you must specify the following entries: 


e On the Calculation specification: 
— EXCPT, as the operation code 
— Blanks or an EXCPT name in factor 2 
¢ On the Output specification: 
— Eincolumn 15 (Type), for the record you want to write 
— Blanks or an EXCPT name in columns 32 through 37 (field name) 


The EXCPT operation writes those records that have an E in column 15 
of the Output specification and that satisfy the conditions specified by the 
conditioning indicators. In addition, if the EXCPT operation has a blank 
factor 2, only exception records with blanks in columns 32 through 37 of 
the Output specification will be written; if the EXCPT operation has an 
EXCPT name in factor 2, only these exception records with the same name 
in columns 32 through 37 of the Output specification will be written. 


You can use indicators in columns 7 through 17 of the Calculation specifi- 
cation. Factor 2 can contain blanks or an EXCPT name. All other columns 
must be blank. 


An EXCPT name can be used on multiple EXCPT output record lines. 
Only exception records, not heading, detail, or total records, can contain 
an EXCPT name. 
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In the following example, line 22 tells VAX RPG II to write the record 

described in line 89 during calculations if indicators 01, 02, and 03 are 

on. Line 34 tells VAX RPG II to write the record described in line 95 if 
indicator 04 is on. 
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16.7.5 FORCE Operation 


The FORCE operation allows you to select the next file from which a 
record is read during multifile processing. You can select primary or 
secondary input and update files. Factor 2 contains the name of the file. 


You can use conditioning indicators, but all other columns must be left 
blank. 


When VAX RPG II executes a FORCE operation it reads, at the next 
program cycle, a record from the file you specify. If you specify more than 
one FORCE operation during the same program cycle, VAX RPG II ignores 
all FORCE operations except the last. 


Although FORCE operations override normal multifile processing, they 
cannot override the first record selected by the program. Reading the first 
record occurs in the first cycle before the first pass through calculations. 


If a FORCE operation is issued for a file that is at its end-of-file, the file is 
not selected for processing. In this case, normal multifile processing logic 
selects the next record. 


In the following example, VAX RPG II reads the next record from the file 
SPECFIL at the next program cycle if indicators 01, 02, and 03 are on. 
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Field length 
Control level | Decimal positions 
[Half adjust (H) 
I! 


| 
| Indicators Operation | 
1 | | | [lResulting 
1 | Factor | Factor Result! llindicators 
1 | 1 | 2 field | [lt - 06 
Cl NxxNxxNxx I | | | | Ils ¢< = +- Comments --+ 
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16.7.6 READ Operation 


The READ operation causes VAX RPG II to read a record from a demand 
or full-procedural file. Factor 2 contains the name of the file from which 
a record is read. You can read a record from the following types of input 
and update files: 


e Sequential and direct disk files processed consecutively 
e Indexed disk files processed sequentially by key or by limits 


You can use any indicators in columns 7 through 17 and in columns 58. 
and 59. VAX RPG II sets on the indicator in columns 58 and 59 when 
an end-of-file condition occurs, or for each READ operation following 
an end-of-file condition. If there is no indicator in columns 58 and 59, a 
run-time error occurs. Columns 18 through 27 and 43 through 57 must 
be left blank, except for WORKSTN files, which can have an indicator in 
columns 56 and 57 to detect an error. See Chapter 6 for information on 
WORKSTN files. 


If VAX RPG II does not open a file because an external indicator is off, a 
READ operation on the file causes an end-of-file condition to occur. 
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In the following example, VAX RPG II reads the next record from the file 
SPECFIL if indicator 99 is off. If an end-of-file condition occurs, 

VAX RPG II sets on indicator 99. If an end-of-file condition does not 
occur, VAX RPG II sets on indicator 99. 


Field length 
Control level 1 Decimal positions 
IHalf adjust (H) 
II 


| 
| Indicators Operation | 
| | {Resulting 
oe ae Factor | Factor Result! [lindicators 
oe ee i | 2 field | {l+- 0 
Cl NxxNxxNxx 1 | | a. | [i> < = +- Comments --+ 
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16.7.7 SETLL Operation 


The SETLL operation positions a file at the next record with a key that is 
greater than or equal to the key you specify in factor 1. Factor 2 contains 
the name of the file for which the lower limit is set. Factor 2 must be an 
indexed demand or full-procedural file being processed sequentially within 
limits. 


Factor 1 can be a field name or a literal, and must be the same size as the 
key specified in the File Description specification. If the keys in the file are 
in packed decimal format, factor 1 must be numeric. | 


You cannot use a record-address file and the SETLL operation on the same 
file. 


If the program issues a READ operation before issuing a SETLL operation, 
processing begins with the first record in the file. | 


When VAX RPG II reaches the end-of-file, you can use another SETLL 
operation to reposition the file. If the SETLL operation is unsuccessful, 
you must reposition the file with a successful SETLL operation. 


When a SETLL operation is performed on a record whose key is greater 
than the highest key in the file, the subsequent READ operation will 

be as if the current record pointer had not changed from the previous 
READ operation. If a successful SETLL operation is followed by a SETLL 
operation for a record whose key is greater than the highest key in the 
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file, with no intervening READ operation, the next READ operation will 
occur as if the current record pointer had not changed from the previous 
READ operation. In the latter case, it appears as if the successful SETLL 
operation never occurred, because it was followed by an unsuccessful 
SETLL operation. 


In the following example, KEY1 contains the lower key limit for the file 
FILE1. The READ operation retrieves the first record with a key that is 
greater than or equal to the field KEY1. 


Field length 
Control level | Decimal positions 
| IHalf adjust (H) 
I] 


| 
| Indicators Operation | 
il | 1 tResulting 
1 | Factor | Factor Result! Ilindicators 
| | | 2 field | lit - 0 
Cl NxxNxxNxx | | | | 1 I> < = += Comments --+ 
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16.8 Branching Operation Codes 


VAX RPG II performs operations in the order they appear in your pro- 
gram. However, you can use branching operation codes to skip or repeat 
operations under certain conditions. 


16.8.1 GOTO Operation 


The GOTO operation transfers program control to the label you specify in 
factor 2. 


The GOTO operation is especially useful in the following situations: 


¢ Skipping calculations when certain conditions occur 
e Performing certain calculations for certain record types 
¢ Repeating calculations 
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You can transfer control in the following ways: 


To a previous line 

From one detail-time calculation line to another 

From one total-time calculation line to another 

From one subroutine calculation to another inside the same subroutine 


You cannot transfer control from the following lines: 


Detail-time calculation line to a total-time calculation line 
Total-time calculation line to a detail-time calculation line 
Line inside a subroutine to a line outside that subroutine 

Line outside a subroutine to a line inside a subroutine 


When using the GOTO operation, the following columns must be left 
blank: 


Columns 18 through 27 (factor 1) 

Columns 43 through 48 (result field) 
Columns 49 through 51 (field length) 
Column 52 (decimal positions) 

Column 53 (half adjust) 

Columns 54 through 59 (resulting indicators) 


16.8.2 TAG Operation 


The TAG operation identifies the line to which program control from a 
GOTO operation branches. Factor 1 contains the same label you used in 
factor 2 of the GOTO operation. 


You cannot use conditioning indicators (columns 9 through 17) to condi- 
tion a TAG operation; however, you can use a control-level indicator if the 
TAG operation is in total-time calculations. 


16-26 Operation Codes 


16.8.3 Example 


In the following example, VAX RPG II branches to line 66 if indicators 67, 
68, and 69 are on. 


Field length 
Control level | Decimal positions 
Ls | [Half adjust (H) 
I 


| Indicators Operation | 
1 | | | [lResulting 
1 | Factor | Factor Result! tlindicators 
an 1 I 2 field | Il+- 0 
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16.9 LOKUP Operation Code 


The LOKUP operation searches for an entry in a table or an array. Factor 
1 contains the search argument and factor 2 contains the name of the table 
or array. The search argument can be an alphanumeric or a numeric con- 
stant, a field name, an array element, or a table name. Search arguments 
must be the same length and format as the entries in the table or array. 
For example, both fields must be numeric with the same number of digits, 
or both must be alphanumeric with the same number of characters. 


You must use at least one, but not more than two, resulting indicators to 
specify the following: 


e The type of search (high, low, or equal) 
e The result of the search (successful or unsuccessful) 
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The following list describes the three types of searches: 


e A resulting indicator in columns 54 and 55 causes VAX RPG II to 
search the table or array for the entry that is nearest to but higher in 
sequence than the search argument. You can specify this search only 
for sequenced tables and arrays. 


e A resulting indicator in columns 56 and 57 causes VAX RPG II to 
search the table or array for the entry that is nearest to but lower in 
sequence than the search argument. You can specify this search only 
for sequenced tables and arrays. 


e A resulting indicator in columns 58 and 59 causes VAX RPG II to 
search the table or array for the entry that is equal to the search 
argument. 


You can use two indicators to test for HIGH and EQUAL or LOW and 
EQUAL conditions. VAX RPG II searches for an entry that satisfies either 
condition, with EQUAL given precedence. You cannot specify both HIGH 
and LOW conditions at the same time. 


If the search is successful, VAX RPG II sets on the resulting indicators. If 
the search is unsuccessful, VAX RPG II sets off the resulting indicators. 


16.9.1 Searching Tables 


The LOKUP operation can search one table or two related tables. When 
searching a single table, you must specify the following: 


e Factor 1 
e Factor 2 
e At least one resulting indicator 


You can specify conditioning indicators in columns 7 through 17. 


When VAX RPG II finds a table entry that satisfies the type of search, 
it places a copy of the entry in a special storage area. If you repeat the 
search, the new entry replaces the previous entry in the storage area. 


When searching for an entry in two related tables, VAX RPG II searches 
only the table specified in factor 2. When the search condition is satisfied, 
VAX RPG II places the corresponding entries in their respective storage 
areas. 
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To program a search for an entry in related tables, you must make the 
following entries: 


* Specify the search argument in columns 18 through 27 


e Specify the name of the table to be searched in columns 33 through 
42 (factor 2). 


¢ Specify the name of the related table in columns 43 through 48 (result 
field). 


e Specify at least one resulting indicator in columns 54 through 59 
(resulting indicators). 


You can specify conditioning indicators in columns 9 through 17. 


Both tables should have the same number of entries. The related | 
table must have as many entries as or more entries than the table to be 
searched. 


Whenever you use a table name in an operation other than a LOKUP 
operation, the table name refers to the data placed in storage by the 

last successful LOKUP operation. Then, you can use the table entry in 
subsequent calculations. If you specify a table name in an operation other 
than a LOKUP operation but before a successful LOKUP operation occurs, 
unpredictable results can occur. 


If you specify the table name as factor 1 in a LOKUP operation, the 
contents of the storage area are used as the search argument. 


You can also use a table as the result field in operations other than a 
LOKUP operation. In this case, the contents of the storage area are 
replaced by the result of the calculation you specify. The corresponding 
entry in the table is also changed. In this way, you can use calculations to 
change the contents of tables. 


Operation Codes 16-29 


In the following example, TABLIS was defined previously as a table. 
VAX RPG II searches for the entry that has the same value as the field 
PARTNO and, if successful, sets on indicator 33. 


Field length 
Control level | Decimal positions 
| IHalf adjust (H) 
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16.9.2 Searching Arrays 


LOKUP operations for arrays are the same as those for tables, except that 
you cannot use the result field. If the element searched for is found, its 
contents are not moved to a storage area. Indicators reflect whether the 
element is present. 


To program a search for an element in an array, you must specify the 
name of the array to be searched in columns 33 through 42 (factor 2). 
Follow the same rules for specifying indicators for arrays as for tables. 


You can specify the element to begin searching by adding an index. The 
index can be a numeric literal or a field. VAX RPG II begins searching at 
the specified element and continues the search until it finds the element 
or it reaches the end of the array. If you use a numeric literal to specify 
the index, VAX RPG II does not change its value to reflect the result 

of the search. If you use a field to specify the index and the search is 
unsuccessful, VAX RPG II places the value of 1 in the field. If you use 

a field to specify the index and the search is successful, VAX RPG II 
places the number of that array element that satisfied the search (counting 
from the first element) in the field. Then, you can use the index field to 
reference that array element in subsequent operations. 
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If you use an index that is less than or equal to zero, or greater than the 
number of elements in the array, and you compile the program with the 
RPG/CHECK=BOUNDS command, VAX RPG II issues a run-time error. 

If you use an index that is less than or equal to zero, or greater than the 
number of elements in the array and you do not compile the program with 
the RPG/CHECK=BOUNDS command, unpredictable results can occur. 


16.9.3 Example 


In the following example, MNTH was defined previously as a sequenced 
array and E as a numeric field. Because 1 is assigned to E, VAX RPG II 
begins searching with the first element of the array and searches for the 
first entry with a value that is greater than and equal to 1000. If an entry 
is found, E will contain the index number of the entry and the indicator 99 


will be set on. If an entry is not found, E will contain 1 and the indicator 
99 will be set off. 


Field length 
Control level 1 Decimal positions 
| IHalf adjust (H) 
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16.10 Subprogram Operation Codes 


VAX RPG II programs can call subprograms written in other languages 
and can pass and receive parameters between the main program and the 
subprogram. See Chapter 12 for examples of subprogram operation codes. 
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16.10.1 CALL Operation 


The CALL operation transfers control to a sab proerank Factor 2 contains a 
character literal or a field defined by the EXTRN operation that names the 
entry point in the subprogram. Factor 2 cannot be a VAX RPG II program 
name. 


The result field can contain the name of the parameter list associated with 
the PLIST operation. This enables it to share parameters between the 
main program and the subprogram. You can also specify the individual 
parameters immediately following the CALL operation code. 


Factor 1, half adjust, and the resulting indicators in columns 54 and 55 
and 58 and 59, must be blank. However, you can specify a resulting 
indicator in columns 56 and 57. VAX RPG II sets this indicator on when 
the subprogram returns an error status. 


16.10.2 EXTRN Operation 


The EXTRN operation initializes the value of a numeric unscaled field to 
a link-time constant. You can use the EXTRN operation to perform the 
following operations: 


¢ Extend the subprogram name to more than eight characters 


e Allow your program to access link-time constants, including status 
codes 


You define link-time constants using external names. Use factor 1 to name 
the field VAX RPG II initializes, using the value of the link-time constant. 
Use factor 2 to name the external constant. You can use a maximum of 
31 characters to name the constant. You must enclose the constant in 
apostrophes. 


The external name must be defined as a global symbol in an object module 
available to the program at link time. Otherwise, an error will occur at 
link time. 


Factor 1 of the EXTRN operation is defined as a nine-digit numeric field 
with zero decimal positions. The field cannot be defined elsewhere in 
the program. Fields defined by an EXTRN operation cannot be used as a 
result field in a calculation or have blank after specified when used on an 
Output specification. 


Conditioning indicators must be left blank. 
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16.10.3 GIVNG Operation 


The GIVNG operation allows you to define a parameter that receives the © 
return status from the subprogram. See the VAX/VMS Run-Time Library 
Routines Reference Manual for information on the definition of return 
status. The GIVNG operation must follow the last PARM, PARMV, and 
PARMD operation following a CALL operation. The result field contains 
the name of an unscaled numeric field, table, or array element. 


Entries in decimal positions and field length are optional. If you specify a 
field length, the entry for decimal positions must be zero. The following 
columns must be left blank: 


¢ Columns 9 through 17 (conditioning indicators) 
¢ Columns 18 through 27 (factor 1) 

© Columns 33 through 42 (factor 2) 

e Column 53 (half adjust) 

e¢ Columns 54 through 59 (resulting indicators) 


16.10.4 PARM Operation 


The PARM operation passes parameters by reference to a subprogram. 
The result field identifies the parameter. The parameter can be a field, 

a table, an array element, or an array. Factor 2 can contain a field, a 
table, an array element, an array, or a literal. The contents of factor 2 
are copied into the result field before the subprogram is called. If the 
result field is numeric, factor 2 must be numeric. In this case, the value 
in factor 2 is copied into the result field in the same way that a Z-ADD 
operation is copied. If the result field is alphanumeric, factor 2 must be 
alphanumeric. In this case, the value is left-justified in the result field and 
trailing characters are filled with blanks. 


The subprogram can change the contents of the result field but cannot 
change the contents of factor 2. Using factor 2 allows you to pass the 
values from factor 2 knowing that the subprogram cannot modify the 
field. 


After a successful CALL operation, VAX RPG II copies the contents of the 
parameter into factor 1. Factor 1 can contain a field, a table, an array, or 
an array element. The copying is done in the same way as for factor 2. 
Entries for factor 1 and factor 2 are optional. 
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Entries in decimal positions and field length are optional. Conditioning 
indicators must be left blank. VAX RPG II, by default, passes numeric data 
by reference in packed decimal format. 


You can also use the PARM operation to convert to the numeric data 
type needed by the subprogram being called. Use columns 54 through 
59 (resulting indicators) to specify the notation for the parameter. See 
Chapter 12 for information on specifying parameters. 


You can use one of the following access types: 


¢ Read-only (R)—the parameter is read by the subprograms, but not 
modified. 


e Write-only (W)—the parameter is not read by the subprograms, but a 
new value is supplied by the subprogram. 


e Modify (M)—the parameter is read by the subprograms and a new 
value is supplied by the subprogram. 

You can use one of the following data types: 

e Word integer (signed) (W) | 

¢ Longword integer (signed) (L) 

¢ Quadword integer (signed) (Q) 

¢ F_floating single-precision (F) 

e D-_floating double-precision (D) 

e Numeric string, right overpunched sign (NRO) 


See Chapter 14 for information on data types. 


You cannot specify an access type or data type if the result field is an 
entire array (nonindexed). 


16.10.5 PARMD Operation 


The PARMD operation passes parameters by descriptor to a subprogram. 
The result field contains the name of the field, the name of an array 
element, the name of the array, or a literal that identifies the parameter. 
Long character literals can be used effectively in the PARMD result field. 
See Section 15.7.5 for information on long character literals. 
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Entries in decimal positions and field length are optional. The following 
columns must be left blank: 

¢ Columns 9 through 17 (conditioning indicators) 

¢ Columns 18 through 27 (factor 1) 

e Columns 33 through 42 (factor 2) 

¢ Column 53 (half adjust) 

¢ Columns 54 through 59 (resulting indicators) 


See the VAX/VMS Run-Time Library Routines Reference Manual for infor- 
mation on argument descriptor format. 


16.10.6 PARMV Operation 


The PARMV operation passes parameters by value to a subprogram. The 
result field contains the name of an unscaled numeric field, table, array, or 
an unscaled numeric literal that identifies the parameter. 


Entries in decimal positions and field length are optional. If you specify 
a field length, the entry for decimal positions must be 0. The following 
columns must be left blank: 

¢ Columns 9 through 17 (conditioning indicators) 

e Columns 18 through 27 (factor 1) _ 

e Columns 33 through 42 (factor 2) 

e Column 53 (half adjust) 

e Columns 54 through 59 (resulting indicators) 


16.10.7 PLIST Operation 


The PLIST operation identifies the name of the parameter list for a subpro- 
gram. Use this operation with the CALL operation to access parameters in 
the subprogram. You can pass a maximum of 255 parameters. 


Factor 1 contains the name of the parameter list. The following columns 
must be left blank: 


e Columns 9 through 17 (conditioning indicators) 
e Columns 33 through 42 (factor 2) 
¢ Columns 43 through 48 (result field) 
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¢ Columns 49 through 51 (field length) 

e Column 52 (decimal positions) 

© Column 53 (half adjust) 

e Columns 54 through 59 (resulting indicators) 


If you want to pass parameters, you must use one of the parameter 
operations (PARM, PARMD, PARMV) to specify how you want to pass 
the parameters. Parameter operations must immediately follow the CALL 
or PLIST operation. Parameter operations must also be in the order 
expected by the subprogram. 


16.10.8 Example 


The following example makes a call to the VAX/VMS Run-Time Library 


routine STR$UPCASE. The call places REP HEAD in the result field 
RESULT. 


Field length 
Control level | Decimal positions 
| IHalf adjust (H) 
Hi 





] 
! Indicators Operation | 
1 | | | J lResulting 
i | Factor | Factor Result! tlindicators 
1 | | | 2 field | JIl+ - 06 
Cl NxxNxxNxx | | I ! | tls < = +- Comments --+ 
0 | 1 | 2 | 4 | 5 | 6 | 7 | 
Res TES CR aa AE ea Te 123456783012345678901234567890123456 7890123456 7830 
HH % % % % H--HEKR HH ¥ 
C MOVE ‘rep head’HEAD 8 
C UPCASE EXTRN’STR$UPCASE’ 
C CALL UPCASE 
C PARMD RESULT 8 
C PARMD HEAD 


2K-4529-85 
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16.11 TIME Operation Code 


The TIME operation code allows you to access the system time of day 
and the optional system date. Note that the system date may be different 
from the date accessed with UDATE, UDAY, UMONTH, or UYEAR if the 
RPG$UDATE logical is used. 


The result field must be numeric with 0 decimal places and contain 
either 6 or 12 digits. A 6-digit result field displays the time in the format 
hhmmss. A 12-digit result field displays the time and date in the format 
hhmmssyymmdd. 


Operation Codes 16-37 


‘sapo) uonesadg §ge-9I 


Table 16-1: Summary of Operation Codes 


Indicators 


Operation Factor 1 Factor 2 Result Control Conditioning Resulting 
Code Field Level +> -~< 0= 


28-32 18-27 33-42 43-48 


Pe 
io.) 
- 
—_ 
a] 


54-55 56-57 58-59 


=) 
a 


ADD" O O+ O= 00 
BEGSR R 
BITOF 
BITON 
CALL 
CHAIN 
COMP' 
DIV" 
DSPLY 
ENDSR 
EXCPT 
EXSR 
EXTRN 
FORCE 
GIVNG 
GOTO 
LOKUP 14 R 
LOKUP I" R 
MOVE 
MOVEA 
MOVEL 
MULT" Oo 
MVR 
PARM O 
PARMD 

PARMV 

PLIST R 
READ 

SETLL R 


OnDW 


OE 
ONR ORL 
OH OL OEQ 
O+ O-= OZ 


OOCOnaD 
On 


9) 


OH OL ~OEQ 
OH OL OEQ 


a 
O BADD ADADD ADDO BADAADAAAD 
C9O000000 0 9820 900000090 0 


DANAMDAWDAAAO 


O EOF 


OOOO OC OOOCOCCOCC OC OOO: 8600 OOOO <O 


aa 
oke) 


sapo) uoljeradg 


6E-91 


XFOOT" 


SETOF' 
SETON' 
SQRT" 
SUB"" 
TAG 
TESTB' 
TIME 


=e) 
oO aA 
am 


Z-ADD" 
Z-SUB" 


Coo O00000 
COO 9 02000 


aan 
Dama 








‘You can specify Half adjust for this operation. 


' Specify at least one resulting indicator for this operation. 


Conditioning indicators are valid only for executable operation codes. 
Fields without entries in this table must be blank. 


'‘* Factor 2 is an array. 


'T Factor 2 is a table. 


Legend 

+ = positive — = negative EOF = end of file 
E = error EQ = equal O = optional 

NR = no record R = required Z = zero 


ZB = zero or blank RL = record locked 


OZ 


OZ 


OZ 
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Appendix A 





Character Sets 
ASCII EBCDIC 

Character Decimal Hexadecimal Decimal Hexadecimal 
NUL 000 00 000 00 
SOH 001 01 001 01 
STX 002 02 002 02 
ETX 003 03 003 03 
EOT 004 04 055 37 
ENQ 005 05 045 2D 
ACK 006 06 046 2E 
BEL 007 07 047 2F 
BS 008 08 022 16 
HT 009 09 005 05 
LF 010 0A 037 25 
VT 011 OB 011 OB 
FF 012 0c 012 0c 
CR 013 0D 013 0D 
SO 014 OE 014 OE | 
SI 015 OF 015 OF 
DLE 016 10 016 10 
DC1 017 11 017 11 
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ASCII EBCDIC 


Character Decimal Hexadecimal Decimal Hexadecimal 
DC2 018 12 018 12 
DC3 019 13 019 13 
DC4 020 14 060 3C 
NAK 021 15 061 3D 
SYN 022 16 050 32 
ETB 023 17 038 26 
CAN 024 18 024 18 
EM 025 19 025 19 
SUB 026 1A 063 3F 
ESC 027 1B 039 27 
FS 028 1C 028 1C 
GS 029 1D 029 1D 
RS 030 1E 030 1E 
US 031 1F 031 1F 
space 032 20 064 40 
033 21 079 4F 
" 034 22 127 7F 
# 035 23 123° 7B 
$ 036 24 091 5B 
% 037 25 108 6C 
& 038 26 080 50 
: 039 27 125 7D 
( 040 28 077 4D 
) 041 29 093 5D 
* 042 2A 092 5C 
; 043 2B 078 4E 
; 044 2c 107 6B 
é 045 2D 096 60 
046 2E 075 4D 
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Character 


Oo WON BD UO fF WON KF O™ 


Gh 


"_ V 


AT“ TAM INe>® 


ASCII 
Decimal 
047 
048 
049 
050 
051 
052 
053 
054 
055 
056 
057 
058 
059 
060 
061 
062 
063 
064 
065 
066 
067 
068 
069 
070 
071 
072 
073 
074 
075 


Hexadecimal 


2F 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
3A 
3B 
3C 
3D 


3E 


3F 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
4A 
4B 


EBCDIC 
Decimal 


097 
240 
241 
242 
243 
244 
245 
246 
246 
248 
249 
122 
094 
076 
126 
110 
111 
124 
193 
194 
195 
196 
197 
198 
199 
200 
201 
209 
210 


Hexadecimal 


61 
FO 
F1 
F2 
F3 
F4 
F5 
F6 
F7 
F8 
F9 
7A 
6E 
4C 
7E 
6E 
6F 
7C 
Cl 
C2 
C3 
C4 
C5 
C6 
C7 
C8 
c9 
D1 
D2 
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ASCII EBCDIC 


Character Decimal Hexadecimal Decimal Hexadecimal 
L 076 4C 211 D3 
M 077 4D 212 D4 
N 078 4E 213 D5 
O 079 4F 214 D6 
P 080 ~ 50 215 D7 
Q 081 51 216 D8 
R 082 52 217 D9 
S 083 53 226 E2 
T 084 54 227 E3 
U 085 55 228 E4 
V 086 56 229 E5 
W 087 57 230 E6 
X 088 58 231 E7 
Y 089 59 232 E8 
Z 090 5A 233 E9 
[ 091 5B 074 4A 
\ 092 5C 224 EO 
] 093 5D 090 5A 
094 5E 095 5F 
ae 095 5F 109 6D 
: 096 60 121 79 
a 097 61 129 81 
b 098 62 130 82 
c 099 63 131 83 
d 100 64 132 84 
e 101 65 133 85 
f 102 66 134 86 
g 103 67 135 87 
h 104 68 136 88 
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Character 
j 
k 


me 


7.0 0 0 3 9 


- 7 NM xX ¢ < c 


~ 


DEL 


ASCII 
Decimal 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 
127 


Hexadecimal 


69 
6A 
6B 
6C 
6D 
6E 
6F 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
7A 
7B 
7C 
7D 
7E 
7F 


EBCDIC 
Decimal 
137 
145 
146 
147 
148 
149 
150 
151 
152 
153 
162 
163 
164 
165 
166 
167 
168 
169 
192 
106 
208 
161 
007 


Hexadecimal 


— 89 


91 
92 
93 
94 
95 
96 
97 
98 
99 
A2 
A3 
A4 
A5 
A6 
A7 
A8 
AY 
CO 
6A 
DO 
Al 
07 
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Appendix B 


Differences Between VAX RPG Il and 
PDP-11RPGII 


This appendix describes the following: 


e PDP-11 RPG II functionality that is not supported by VAX RPG II 


e VAX RPG II functionality that is supported differently than 
PDP-11 RPG II functionality 


° Additional functionality that is supported only by VAX RPG II 


This appendix does not list new features which have been added to 
VAX RPG II Versions 2.0 and 2.1. See the online release notes for details 
of the new features in Version 2.1. 


VAX RPG II does not support the following PDP-11 RPG II functionality: 


e¢ Control specification (H) 
— Column 11 (listing options)—the equivalent functionality is 
implemented using the /LIST qualifier to the DCL command RPG. 
— Column 15 (debug)—the DEBUG operation code is not supported. 
Instead, use the VAX/VMS Debugger. 
— Column 25 (source listing)—a single page size for the listing is 
supported. 
e Extension specification (E) 
— Columns 11 through 18 (from file name)—PDP-11 RPG II al- 
lows the same table input file to be specified for more than one 


preexecution-time table or array: VAX RPG II requires a different 
file for each preexecution-time table or array. 
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e¢ Calculation specification (C) 


— Columns 28 through 32 (operation)—the DEBUG operation code 
is not supported. 


e¢ Output specification (O) 


— Column 39 (blank after)—specifying blank after for a constant 
field is not supported. 


¢ General 
— VAX RPG II uses PRN format files for printer output files. This 
format requires that you use the /NOFEED qualifier with the 
PRINT command when printing printer output files. 
— PDP-11 RPG II handles both zoned numeric and overpunched 


decimal data formats for input. VAX RPG II supports only over- 
punched decimal data format. 


— All user-defined names must be unique for VAX RPG II. 


— VAX RPG II does not support the HO indicator. Errors detected by 
VAX RPG II result in run-time errors. 


— VAX RPG II does not recognize LO as an indicator. Although 
LO can be used as a control-level indicator in columns 7 and 8 
of the Calculation specification, it cannot be used in an Output 
specification. 


VAX RPG II supports the following functionality differently than 
PDP-11 RPG I: 


e File specification (F) 
— Column 15 (file type)—when O (output) is entered in column 
15 and column 66 (file addition) does not contain A, VAX RPG 
II always creates a new version of the file, even if the file is an 


indexed or direct file. PDP-11 RPG II accesses an existing indexed 
or direct file if the specified file is found. 


— Columns 40 through 46 (device code)—VAX RPG II uses the 
device code to define the functions that can be performed on the 
associated file. It does not refer to a specific device. 


— Columns 47 through 52 (symbolic device)—VAX RPG II uses the 
symbolic device in conjunction with the file name specified in 
columns 7 through 14 (file name) to associate the VAX RPG I file 
name with the VAX/VMS file specification. 
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If you specify a symbolic device on the File Description specifi- 
cation and no VAX/VMS logical name translation exists for that 
symbolic device, then VAX RPG II will have VAX RMS use the 
symbolic device as the file name. 


If a symbolic device consists of all blanks, then VAX RMS will 
operate as if the symbolic device did not exist (for example, an 
attempt will be made to translate the file name as a logical name). 
The symbolic device may consist of any characters and will be 
passed to VAX RMS when the file is opened. 


The file name will be translated as a logical name if a symbolic 
device is not supplied. The hierarchy by which the file name is 
constructed by VAX RMS is as follows: 


1. File name (symbolic device) 
2. Default file name (VAX RPG II file name) 
3. Related file name (DAT file type) 


The related file name can be overridden by supplying a different 
file type for the symbolic device. 


— Column 68 (share)—VAX RPG II requires you to specify S or R to 
open a file for shared access. PDP-11 RPG II requires you to use 
the /MULTIUSER qualifier with RPGASN. 

e Input specification (I) 

— Column 43 (data format)—when loading an execution-time array 
from an Input specification that is in packed decimal or binary 
format, VAX RPG II requires packed decimal (P) or binary (B) in 
column 43 of the Input specification. PDP-11 RPG II requires 
packed decimal (P) or binary (B) in column 43 on the Extension 
specification. 

e Calculation specification (C) 


— A READ operation code on a file that has not been opened 
because it was conditioned by an external indicator that was off, 
sets on the end-of-file indicator if one is specified. In this case, 
PDP-11 RPG II does not set on the end-of-file indicator. 


— VAX RPG II MOVE and MOVEL semantics are not the same as 
those of PDP-11 RPG II when the result field is numeric. The 
differences are the following: 


1. VAX RPG II does not perform the “spurious sign” and “sign 
ignored” cases of PDP-11 RPG II. 
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2. When the sending field is a character field, VAX RPG II 
converts the characters in the sending field in the following 
manner: 


* All valid overpunched decimal characters are converted to 
the sign and digit they represent. 


* All other characters are converted to a positive zero (+0). 


3. If a READ operation is done before a SETLL operation, 
VAX RPG II reads the record with the lowest key. PDP-11 
RPG II reads a record containing blanks in this case. 


4, PDP-11 RPG II does not issue an error when the DSPLY 
operation code is used with a field that is larger than the file 
record length. VAX RPG II does issue an error miesane in this 
case. 


5. VAX RPG II will display (DSPLY operation code) the sign of a 
negative numeric. 


e Output specification (O) 


Columns 17 and 18 (space after)—PDP-11 RPG II assumes a 
single space after if the entries in columns 17 and 18 are left blank 
or are zero. VAX RPG II assumes a single space after only if all 
entries in columns 17 through 22 are left blank. An entry of zero 
in columns 17 and 18 allows overprinting. 


¢ General 


ALTSEQ records—VAX RPG II uses hexadecimal representation to 
specify the entries in ALTSEQ records. PDP-11 RPG II uses octal 
representation. 


Tables—For VAX RPG II, a reference to a table before the first 
LOKUP operation will locate the first element in the table. 
PDP-11 RPG II returns a blank. 


VAX RPG II and PDP-11 RPG II support two-word (4- byte) binary 
data. PDP-11 RPG II places the words in reverse order to what 

is required by VAX architecture. PDP-11 RPG II data files that 
include two-word (4-byte) binary data will require conversion to 
be used by VAX RPG II. 

VAX RPG II uses the logical name RPG$UDATE to specify UDATE 
and uses the logical name RPG$EXT_INDS to specify the settings 
for external indicators. 

PDP-11 RPG II treats blanks in a numeric field in overpunched 
decimal format as zeros. VAX RPG II does the same when you 
use the /CHECK=BLANKS_IN_NUMERICS qualifier with the 
RPG command. 
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— VAX architecture reports a reserved operand fault when invalid 
data is found in a numeric field. For VAX RPG II, this causes a 
run-time error. PDP-11 RPG II processes invalid numeric data 
without halting program execution. 

— PDP-11 RPG II's run-time system changes the name of the process 
to the program name while the program is running. VAX RPG II 
does not do this. 

— When compiling with RPG [FOO]TEST.RPG, PDP-11 RPG II 
places the OBJ, LST, CMD, and ODL files in the [FOO] directory, 
no matter what the current default directory is. 


VAX RPG II places the OBJ and LIS files into the default directory 
in a manner similar to other VAX languages. This VAX RPG II 
operation is similar to the following PDP-11 command lines: 


$ MCR PDPRPG 
RPG>TEST= [F00] TEST .RPG 
RPG>CTRL/Z 


The preceding commands cause PDP-11 RPG II to place the files 
in the current default directory. 


Use the following command to simulate the PDP-11 RPG II 
operation: 
$ RPG [FOO] TEST/LIS/OBJ 


— /NOLIST is the default for invoking the VAX RPG II compiler 
interactively. PDP-11 RPG II produces a listing file by default. 


Note that RPGDMP is not provided with VAX RPG II. A similar func- 
tionality is provided with the VAX/VMS Dump and Sort/Merge Utilities 
(DUMP and SORT/MERGE). See the VAX/VMS DCL Dictionary for infor- 
mation on DUMP and SORT/MERGE. See the VAX/VMS Utility Reference 
Manual for information on the three SORT qualifiers, /CONDITION, 
/FIELD, and /INCLUDE. 


VAX RPG II supports the following additional functionality: 


¢ Control specification (H) 
— A Control specification (H) is not required. 


— Column 18 (currency symbol)—you can specify the character to 
represent the currency symbol. 
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Column 21 (inverted print)—an entry of I, D, or J switches the 
function of decimal point and comma notation in numeric literals 
and edited formats, and changes the format of UDATE to day, 
month, and year (ddmmyy). 


e File specification (F) 


Columns 7 through 14 (file name)—file names can be up to eight 
characters long. 


Column 16 (file designation)—-VAX RPG II does not require a 
primary file. 

Column 19 (file format)—you can specify V to indicate that the 
file contains variable-length records. 


Columns 24 through 27 (record length)—VAX RPG II allows all 
files, with the exception of display files, to have a record length of 
up to 9999 characters. 


e Extension specification (E) 


The definition of compile-time tables and arrays can be mixed 
with the definition of execution-time and preexecution-time tables 
and arrays. 


e Input specification (I) 


Columns 15 and 16 (sequence)—you can specify input records 
with an alphabetic sequence before or after inputi records with a 
numeric sequence. 


Columns 19 and 20 (record-identifying indicator)—you do not - 
have to specify look-ahead fields as the last record in a file. 


e¢ Calculation specification (C) 


Columns 28 through 32 (operation)—the following operations 
have been added to allow VAX RPG II programs to call subpro- 
grams written in other languages and routines in the VAX/VMS 
Run-Time Library and system services: 


1. CALL—calls a subprogram with optional parameters 
PARM—>passes a parameter by reference 
PARMD—passes a parameter by descriptor 
PARMV—passes a parameter by value 
GIVNG—returns the status of a subprogram 


EXTRN—equates a VAX RPG II name with an external link- 
time constant 


7. PLIST—defines a parameter list 


a a a 


B-6 Differences Between VAX RPG Il and PDP-11 RPG Ii 


Columns 28 through 32 (operation)—VAX RPG II allows factor 
2 and the result field to reference the same array on a MOVEA 
operation. 

Columns 49 through 52 (field definition)—you do not have to 
define fields before they are used, if they are defined within the 
program. 


Output specification (O) 


Columns 16 through 18 (ADD/DEL)—you can specify the DEL 
option to identify the record to be deleted. You can delete records 
from indexed or direct files. 

Columns 45 through 70 (edit word)—the number of replaceable 
characters in the edit word can be greater than or equal to the 
number of digits in the numeric field. 


General 


The string containing double slashes (//) and a blank and the 
string containing a double asterisk (**) and a blank are accepted 
as delimiters between specifications and any ALTSEQ records, and 
between compile-time tables and arrays. 

The special words, *IN and *INxx, can be used to reference 
indicators as one-position character fields. 

A user-defined name can contain a pound sign (#), an underscore 
(—), a dollar sign ($), and an at sign (@). 

A character field can have a length of up to 9999 characters. 


The VAX RPG II editor does not support the following PDP-11 RPG II 
features: 


Editing of SORT-11 specifications 
VTO5 or VT52 terminals 
Hard-copy terminals 


The following qualifiers: 


/IDENT 

/PAGE and /NOPAGE 
/SAVE and /NOSAVE 
/TERMINAL 


CTRL/D 
SET SKIP command 


Ne 
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e Automatically advancing the cursor to the next tab stop if the current 
field is full 


e Displaying a tab stop as data from an input file as the TAB character 
e Renaming the input file with a BAK file type 
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Appendix C 


VAX Performance Coverage Analyzer 
Applied to a VAX RPG II Program 





The following command procedure produces execution information by 
source line. (Note that for purposes of illustration, unimportant informa- 
tion on the accompanying listing is truncated on the right side.) 


$ rpg/debug/nolist ships 

$ link/debug=sys$library : pca$obj.obj/nomap ships 
$ run ships 

set datafile ships 

set counters program_address by line 

go 

$ pca ships 

tabulate/counters/source module ships by line 
file pcea.lis 

exit 

$ type pca.lis 


VAX Performance and Coverage Analyzer Page i 
Exact Execution Counts (164 data points total) 
Percent Count Line 
SHIPS\ 
1: H*++ 
2: H* FUNCTIONAL DESCRIPTION: 
3: H* This program produces a report of shipments f 
4: H* products broken down by division and departme 
5: H* input file with the shipment data for the pas 
6: H¥-- . 
T: H. 
0.6% 1 8: FSHIPS IP F 41 DISK 
0.6% 1 9: FSUMREP O F 98 LPRINTER 
10: E QTY 4 20 
11: LSUMREP 55FL 500L 
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12.2% 20 12: ISHIPS AA O01 


13: I 1 6 DIV 
14: I 6 7 DEPT 
15: I 8 16 PROD 
16: I 17 24 QTY 
17: Ce : 
24.4% 40 18: Cc ol XFOOTQTY PROQTY 30 
24.4% 40 19: Cc 01 PROQTY ADD DEPQTY DEPQTY 30 
20: C* (Li break on DEPT / L2 break on DIV) 
4.3% 7 21: CL1i DEPQTY ADD DIVQTY DIVQTY 30 
4.3% 7 22: CL1 Z-ADDO DEPQTY 
2.4% 4 23: CL2 DIVQTY ADD FINQTY FINQTY 40 
24: C* 
0.6% 1 25: OSUMREP H 001 1P 
26: 0 48 ‘PRODUCT SHI 
0.6% 1 a7: 0 HO2 P 
28: 0 UDATE Y 12 
, 29: 0 48 ‘PRODUCT SHI 
0.6% 1 30: 0 H 1 96 4P | 
31: 0 42 'SHIPMENTS' 
0.6% 1 32: 0 H 2 14? 
33: 0 15 ‘DIVISION D 
34: 0 24 "PRODUCT! 
35: 0 48 'Q1 Q2 Q3 
12.2% 20 36: 0 Di 01 
37: 0 L2 DIV 8 
38: 0 Li DEPT 14 
39: 0 PROD 25 
40: 0 QTY 2Z 41 
aa: 0 PROQTYZ 48 
4.3% 7 42: 0 T1 U1 
2.4% 4 43: 0 T O L2 
44: 0 DIV 69 
2.4% 4 45: 0 T O L2 
46: 0 DIV 69 
2.4% 4 47: 0 T 02 L2 
48: 0 DIVQTYZB 48 
49: 0 63 '<== Total f 
50: 0 DIV 69 
0: 6% 1 61: 0 T O LR 
52: 0 FINQTYi1 48 
53: 0 


65 '<== GRAND T 
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INDEX 





*FMSSTA ® 6-18 
*FMSTER ® 6-18 
*operation code ® 6-17 
*RECORD ® 6-18 
*STATUS ® 6-17 


A 


Access mechanism ® 12-25 
Adding records ® 8-27 to 8-31 
Additional I/O area ® 15-36 
rules for specifying ® 15-36 
Addition operation ® 16-3 
ADD operation code ® 16-3 
example ® 16-5 
ADD option ® 15-118 
example ® 15-118 
rules for specifying ® 15-118 
ADDROUT files 
creating ® 8-17 
example ® 8-18, 8-19, 8-21 
rules for specifying ® 8-19 to 8-20 
specifying 
key length ® 15-34 
ADVANCE function ® 2-25 
Alternate array ® 15-59 
Alternate collating sequence ® 15-15, 15-16 
specifying 
example ® 15-17 
Alternate format 
arrays ® 11-10 
compile-time ® 11-10 
example ® 11-11 


Alternate format 
arrays (cont’d.) 
preexecution-time ® 11-10 
related ® 11-10 
Alternate table ® 15-59 
AND ® 15-77, 15-114 
example ® 15-78 
Output specification 
example ® 15-115 
rules for specifying ® 15-78, 15-114 
Appended list ® 3-4 
Append list ® 15-7 
Arguments 
optional ® 12-17 
Arithmetic operation codes ® 16-1 
ADD ® 16-3 
Blank factor 1 ® 16-3 
DIV ® 16-4 
blank factor 1® 16-4 
example ® 16-5 
MULT ® 16-3 
blank factor 1® 16-3 
MVR ® 16-4 
rules ® 16-1 
signs ® 16-2 
SORT ® 16-4 
SUB ® 16-3 
blank factor 1® 16-3 
XFOOT ® 16-5 
Z-ADD ® 16-3 
Z-SUB ® 16-3 
Array elements 
outputting ® 11-24 
referencing ® 11-17 
searching ® 11-19 
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Array elements (cont’d.) 
XFOOT operation code ® 11-17 
Arrays ® 11-1 
addition operation ® 16-5 
alternate format ® 11-10, 15-59 
IN,n indicators® 7-22 — 
IN indicators ® 7-22 
compile-time ® 11-2 
example ® 11-3 
creating ® 11-4 
array input records ® 11-4 
definition ® 11-1 
execution-time ® 11-4 
in calculations ® 11-12 
example ® 11-14 
input records 
example ® 11-5 
loading time 
selecting ® 11-1 
LOKUP operation code ® 11-17, 16-30 
example ® 11-19 
MOVEA operation code ® 11-21 
example ® 11-22 
moving data® 11-21, 16-7 
example ® 11-22 
names ® 14-8 . 
outputting 
array elements ® 11-24 
example ® 11-24 
entire arrays ® 11-23 
preexecution-time ® 11-4 
referencing ® 11-12 
array elements ® 11-12 
example ® 11-17 
entire arrays ® 11-12 
related ® 11-5 
resulting indicators ® 11-18 
searching ® 11-17, 16-30 
example ® 11-18, 16-34 
searching for elements ® 11-19 
specifying ® 11-6, 15-22 . 
alternate format ® 15-59 
data format ® 15-56 
decimal positions ® 15-57 
elements ® 11-14 
from file name ® 15-51 
length of entry ® 15-55 
names ® 15-53 
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Arrays 
specifying (cont'd.) 
number of entries per record ® 15-54 
number of entries per table or array ® 
15-55 
sequence ® 15-58 
to file name ® 15-52 
transferring data ® 16-7 
types 
compile-time ® 11-2 
execution-time ® 11-4 
preexecution-time ® 11-4 
updating ® 11-22 
example ® 11-23 
using ® 11-1 
writing 
array elements ® 11-24 
example ® 11-24 
entire arrays ® 11-23 
XFOOT operation code ® 16-5 
example® 11-16 
ASCII character set ® A-1 
Asterisk indicator (*) ® 13-3 
Asterisk protection ® 15-140 
Automatic overflow ® 9-15 


BACKUP function ® 2-25 
BEGSR operation code ® 16-12 
example ® 16-13 
rules ® 16-12 
IN,n indicators ® 7-22 
example ® 7-22 
function ® 7-22 
specifying array elements ® 7-22 
IN indicators ® 7-22 
example ® 7-22 
function ® 7-22 
specifying arrays ® 7-22 
INxx indicators ® 7-23 
example ® 7-23 
function ® 7-23 
representing indicators ® 7-23 
Binary data types 
longword ® 14-4 
specifying ® 15-56 


Binary data types (cont’d.) 
word ® 14-3 
BITOF operation code ® 16-14 
example ® 16-15 
rules ® 16-14 
BITON operation code ® 16-13 
example ® 16-15 
rules © 16-14 
Bit operation codes ® 16-13 
BITOF ® 16-14 
BITON ® 16-13 
example ® 16-15 
TESTB ® 16-14 
Bits 
setting off ® 16-14 
setting on® 16-13 
testing ® 16-14 
Blank after ® 15-131 
example ® 15-132 
rules for specifying ® 15-131 
Blank factor 1 
example ® 16-5 
Block length ® 15-26 
rules for specifying ® 15-27 
BOTTOM function ® 2-25 
Branching operation codes ® 16-25 
example ® 16-27 
GOTO ® 16-25 
TAG ® 16-26 
BS_KEY ® 2-34, 2-68 
Buffers ® 2-11 
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Calculations 
arrays ® 11-12 
documenting ® 15-112 
operations 
addition ® 16-3 
division ® 16-4 
multiplication ® 16-3 
square root ® 16-4 
subtraction ® 16-3 
referencing 
array elements ® 11-12 
entire arrays ® 11-12 
result field ® 15-107 


Calculations (cont’d.) 
rounding data ® 15-109 
saving the remainder ® 16-4 
specifying 
decimal positions ® 15-109 
factor 1® 15-104 
factor 2 ® 15-104 
field length © 15-108 
operation codes ® 15-107 
resulting indicators ® 15-110 
totaling data ® 7-17 
using indicators ® 15-101 
~ control-level ¢ 7-9 
resulting ® 7-6 
Caiculation specification © 15-98 
comments ® 15-112 
control-level indicators ® 15-99 
decimal positions ® 15-109 
factor 1® 15-104 
factor 2 ® 15-104 
field length ® 15-108 
format ® 15-98 
half adjust © 15-109 
Indicators ® 15-101 
long character literal® 15-104 
operation codes ® 15-107, 16-1 
result field ® 15-107 
resulting indicators ® 15-110 
type ® 15-99 . 
Calculation specifications 
WORKSTN ® 6-5 
Calling 
subprograms ® 12-32 
system services ® 12-28 
VAX/VMS Run-Time Library procedures ® 
16-32 
Call interface ® 12-1 
subprograms ® 12-32 
system services ® 12-28 
CALL operation code ® 16-32 
example ® 16-36 
rules ® 16-32 
Card reader device 
specifying ® 15-38 
Chained files 
input 
selecting mode of processing ® 15-33 
logic cycle ® 1-20 


Index-3 


Chained files 
logic cycle (cont’d.) 
flowchart ® 1-20 
update 
selecting mode of processing ® 15-33 
CHAIN operation code ® 16-17 
example ® 16-19 
indicator for locked record ® 16-17 
reading records ® 16-17 
rules © 16-17 
Character 
see record identification codes 
Character data type 
example ® 14-2, 14-3 
CHARACTER function ® 2-31 
Character sets 
ASCII ® A-1 
decimal ® A-1 
EBCDIC ® A-1 
hexadecimal ® A-1 
CHECK qualifier © 3-6 
checking 
array boundaries ® 3-6 
blanks in numeric fields ® 3-6 
recursive calls to subroutines ® 3-6 
format ® 3-6 
options ® 3-6 
BLANKS_IN_NUMERICS ® 3-6 
BOUNDS ® 3-6 
RECURSION @ 3-6 
Codes, device 
specifying 
WORKSTN ® 15-38 
Collating sequences ® 15-16 
alternate ® 15-15 
ASCII ® 15-15 
EBCDIC ® 15-15 
specifying 
example @ 15-17 
COLUMN function ® 2-32 
80-column ruler ® 2-6 
definition * 2-9 
COMMAND function ® 2-22 
example ® 2-82 
Command keys ® 6-10, 6-11 
selective enabling ® 6-13 
user-defined ® 6-12 
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Command line 
conditions ® 2-36 
COMMAND option ® 2-50 
COMMAND qualifier ® 2-3 
Commands 
DCL ® 3-1 
debugger ® 5-4 
VAX RPG II editor © 2-36 
RUN ® 3-12 
Comments ® 15-5, 15-112 
rules for specifying ® 15-5 
Compare operation codes 
COMP ® 16-16 
Compiler directives ® 15-5 
COPY ® 15-6 
COPY_CDD ® 15-7 
Compiler error messages ® 3-12 
format ® 3-12 
IDENT field ¢ 3-13 
interpreting ® 3-12 
Compiler listing ® 4-1 
command qualifiers © 4-8 
copy directive ® 4-8 
cross-reference information 
CROSS_REFERENCE qualifier © 4-8 
indicators ® 4-8 
user-defined names ® 4-8 
example ® 4-8 
identification © 4-8 
interpreting ® 4-1 
machine-generated code ® 4-8 
MACHINE—CODE qualifier ® 4-8 
PSECTs ® 4-8 
source code ® 4-8 
_ Statistical information ® 4-8 
Compiler options 
default © 3-3 
example ® 3-3 
Compile-time arrays ® 11-2 
advantages ® 11-2 
creating ® 11-5, 11-7 
example ® 11-7 
rules for specifying ® 11-5 
example ® 11-3 
outputting ® 11-23 
updating ® 11-22 
writing ® 11-23 
Compile-time tables ® 10-2 


Compile-time tables (cont'd.) 
advantage ® 10-2 
example ® 10-2 
input records 
creating ® 10-3 
rules for specifying ® 10-3 
outputting ® 10-13 
rules for defining ® 10-7 
searching 
example ® 10-11 
writing ® 10-13 
Compiling programs ® 3-1 
example ® 3-2 
generating an object module ® 3-2 
specifying more than one program ® 3-2 
COMP operation code ® 16-16 
example ® 16-17 
rules © 16-16 
Condition values 
returned ® 12-20 
signaled ® 12-20 
Constants ® 15-137 
rules for specifying ® 15-138 
Control breaks 
identifying ® 7-9 
split-control fields ® 7-12 
Control-level indicators ® 7-9, 15-90, 15-99 
conditioning data ® 15-90 
control breaks ® 7-9 
example ® 7-9, 15-91, 15-101 
function ® 7-9 
hierarchy ® 7-9 
identifying control breaks ® 7-9 
rules for specifying ® 15-90 
signaling changes in control fields ® 7-9 
split-control fields ® 7-12 
Control specification ® 15-13 
alternate collating sequence ® 15-15 
currency symbol ® 15-14 
example ® 15-18 
format ® 15-13 
forms library name ® 15-18 
forms position ® 15-17 
inverted print © 15-14 
type ® 15-13 
Conversion | 
from S and D specifications ® 6-25 
manual conversion ® 6-30 


Conversion (cont’d.) 
multiple input constants ® 6-32 
output/no input fields © 6-32 
- utility program conversion ® 6-26 
VAX RPG Il indicators ® 6-31 
Conversion utility 
overview ® 6-26 
COPY_CDD qualifier © 15-7 
COPY qualifier® 15-6 | 
Core index ® 15-41 
rules for specifying ® 15-41 
CREATE qualifier ® 2-4 
Creating files 
buffers ® 8-49 
CROSS_REFERENCE qualifier ® 3-7 
cross referencing 
indicators ® 3-7 
user-defined fields ® 3-7 
format ® 3-7 
generating cross-reference information ® 4-8 
C specification 
INFDS ® 6-16 
CTRL_Z_KEY 
example ® 2-76 
Currency symbol ® 15-14 
rules for specifying ® 15-14 
Current workspace ® 6-9 
Cursor ® 2-10 
CUT function ® 2-26 
example ® 2-85 
CZD portion 
See record identification codes 


Data 
comparing contents ® 16-16 
displaying ® 16-19 
moving ® 16-6 
moving from the left ® 16-8 
repeating ® 9-9 
transferring © 16-6 

Data formats 
binary ® 15-56 
Extension specification ® 15-56 
Input specification © 15-79 
Output specification ® 15-134 
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Data formats 
Output specification (cont’d.) 
example ® 15-135 
overpunched decimal ® 15-56 
packed decimal ® 15-56 
Data structure ® 15-65 
Data structures ® 15-67 
examples of using ® 15-83, 15-84, 15-85, 
15-86 
local data area ® 15-70 
examples ® 15-88 
updating files © 8-31 
Data structure subfield ® 15-68 
Data types ® 14-2 
binary ® 14-3 
character ® 14-2 
overpunched decimal ® 14-5 
packed decimal ® 14-4 
specifying ® 15-56 
Date 
formatting ® 9-4 
printing ® 9-4 
DCL commands 
RPG ® 3-1 
DCL RPG command ® 3-1 
default compiler options ® 3-2 
qualifiers © 3-5 
example ® 3-4 
Debugger commands 
CANCEL BREAK ® 5-7 
CANCEL TRACE ® 5-9 
CANCEL WATCH ® 5-10 
CTRL/Y @5-14 
DEPOSIT ® 5-17 
EDIT @ 5-14 
EVALUATE ® 5-18 
EXAMINE ® 5-15 
EXIT @5-15 
GO ® 5-12 
SET @ 5-8 
stepping through a TAG ® 5-8 
stepping through subroutines ® 5-8 
SET BREAK ® 5-7 
SET LANGUAGE ® 5-5 
SET STEP ® 5-12 
SET TRACE ® 5-9 
SET WATCH ® 5-10 
SHOW BREAK ® 5-7 
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Debugger commands (cont’d.) 


SHOW CALLS ® 5-11 
SHOW LANGUAGE @ 5-5 
SHOW TRACE ® 5-9 
SHOW WATCH ® 5-10 
STEP ® 5-12 
qualifiers 
INTO ® 5-13 
LINE ® 5-13 
OVER ® 5-12 
SOURCE @ 5-13 
SYSTEM ® 5-12 
TYPE ® 5-13 
Debugging VAX RPG Il programs ® 5-1 
debugger commands 
table © 5-4 
*DETC logic cycle label © 5-6 
*DETL logic cycle label © 5-6 
displaying source code ® 5-13 
edit the file you are debugging ® 5-14 
evaluating expressions ® 5-18 
examining 
array elements ® 5-7 
contents of 
‘array elements ® 5-15 to 5-16 
I/O buffers © 5-15 to 5-16 
table entries © 5-15 to 5-16 
variables ® 5-15 to 5-16 
data ® 5-7 
locations ® 5-15 
table entries ® 5-7 
executing program lines ® 5-12 
*GETIN logic cycle label ® 5-6 
leaving the debugger ® 5-15 
modifying 
array elements ® 5-7, 5-17 
data ® 5-7 
locations ® 5-15 
table entries ® 5-7 
variables ® 5-17 
*OFL logic cycle label © 5-6 
referencing 
array elements ® 5-7 
data ® 5-7 
line numbers ® 5-3 
logic cycle labels ® 5-6 
table entries ® 5-7 
resuming program execution ® 5-12 


Debugging VAX RPG Il programs (cont’d.) 


returning to system command level ® 5-14 
setting 
breakpoints ® 5-7 
indicators ® 5-17 
tracepoints ® 5-9 
watchpoints ® 5-10 
subprograms ® 5-11 
suspending program execution ® 5-9 
table entries ® 5-15 to 5-16 
*TOTC logic cycle label ® 5-6 
*TOTL logic cycle label ® 5-6 
tracing calls © 5-10 
DEBUG qualifier ® 3-7, 5-1 
format ® 3-7 
options ® 3-7 
SYMBOLS ® 3-8 
TRACEBACK ® 3-8 
providing 
an address correlation table ® 3-8 
information for the VAX/VMS Debugger ® 
3-7 
local symbol definitions ® 3-8 
DEBUG qualifiers 
ALL ® 5-2 
NONE ® 5-2 
SYMBOLS ® 5-2 
TRACEBACK ® 5-2 
Decimal character set ® A-1 
Decimal positions ® 15-57, 15-81, 15-109 
rules for specifying ® 15-57, 15-81, 15-109 
Default compiler options.® 3-2 
DEFAULT option ® 2-51 
DELETE_CHARACTER function ® 2-34 
DELETE_FIELD function ® 2-24 
DELETELINE function ® 2-21 
DELETE_TO_BEGINNING_OF_LINE function ® 2-35 
example ® 2-30 
Deleted-field buffer © 2-11 
Deleted-line buffer ® 2-11 
DEL option ® 15-118 
example ® 15-119 
rules for specifying ® 15-118 
Demand files 
logic cycle ® 1-20 
flowchart ® 1-20 
READ operation code ® 16-23 
selecting mode of processing ® 15-29 


DEPOSIT ® 5-17 
Detail time 
processing individual records ® 1-9 
Detail-time ® 1-5 
Developing programs 
creating 
example ® 2-62 to 2-63 
generating a listing file © 4-1 
Device codes ® 15-38 
rules for specifying ® 15-39 
specifying 
card reader ® 15-38 
disk ® 15-38 
magnetic tape ® 15-38 
printer ® 15-38 
terminal ® 15-38 
WORKSTN ® 15-38 
Direct file organization ® 8-4 
example ® 8-4 
Direct files 
adding records ® 8-29 
example ® 8-29, 8-30 
rules for specifying ® 8-29 
creating ® 8-25 
example ® 8-25 
rules for specifying ® 8-25 
updating records 
rules for specifying ® 8-33 
Directives, compiler ® 15-5 
COPY ® 15-6 
COPY_CDD ® 15-7 
Disk device 
specifying ® 15-38 
DISPLAY function ® 2-23 
example ® 2-73 
Division operation ® 16-4 
saving the remainder ® 16-4 
DIV operation code ® 16-4 
example ® 16-5 
DOWN function ® 2-33 
D specification ® 6-25, 6-29 
DSPLY operation code ® 16-19 
displaying data ® 16-20 
example ® 16-20 
rules ® 16-20 
Duplicate field names ® 6-31 
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EBCDIC character set ® A-1 
Edit code modifiers ® 15-135 
example ® 15-137 
rules for specifying ® 15-136 
Edit code modifiers 
asterisk fill ® 9-2 
floating dollar sign ® 9-2 
Edit codes ® 15-128 
combined ® 9-2 
constants 
example ® 9-3 
rules for specifying ® 9-3 
example ® 15-130 
modifiers ® 9-2 
printer output files © 9-2 
rules for specifying ® 15-129 
simple ® 9-2 
specifying 
notation ® 15-14 
Editing buffer ® 2-11 
Editing window ® 2-6 
Editor 
See. VAX RPG II 
Edit words ® 15-138 
body ® 15-138 
example ® 15-140 
expansion® 15-139 
rules for specifying ® 15-143 
sign status ® 15-138 
specifying 
asterisk protection ® 15-140 
blank spaces ® 15-140 
commas ® 15-141 
CR® 15-143 
currency symbol ® 15-140 
decimal points © 15-141 
negative signs ® 15-143 
zero-suppression ® 15-139 
END_OF_LINE function ® 2-29 
example ® 2-29 
End-of-file © 15-24 
rules for specifying ® 15-24 
End position ® 15-132 
example ® 15-133 
rules for specifying ® 15-133 
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ENDSR operation code ® 16-12 
example ® 16-13 . 
rules ® 16-12 

ENTER function ® 2-32 

ENTER key 
example ® 2-78 

EOB mark ® 2-9 

Error messages 
compiler ® 3-12 
IDENT field values ® 3-13 

Errors 
DUPFLDNAM ® 6-31 
handling ® 7-19 

halt indicators ® 7-19 

EVALUATE®5-18 

EXAMINE ® 5-15 

EXCPT 
names ® 14-8 

EXCPT name ® 15-127 

EXCPT operation code ® 16-21 
writing records during calculations ® 16-21 

Execution-time arrays ® 11-4 
creating ® 11-4, 11-9 

example ® 11-9 
rules for specifying ® 11-4 
loading 
example ® 11-10, 11-15 
outputting ® 11-23 
example ® 11-24 
specifying 
array elements 
example ® 11-15 
entire arrays . 
example ® 11-15, 11-16 
writing ® 11-23 
example ® 11-24 

EXIT function ® 2-35 

Expansion factor ® 15-43 
improving search efficiency ® 15-43 
preventing bucket splitting © 15-43 
table ® 15-44 

EXSR operation code ® 16-12 
example ® 16-13 
rules ® 16-12 

Extension code ® 15-37 

Extension specification 
comments ® 15-59 
data format ® 15-56 


Extension specification (cont'd.) 
decimal positions © 15-57 
defining 
arrays ® 15-50 
record-address files ® 15-50 
tables ¢ 15-50 
example ® 15-59 
format ® 15-51 
from file name ® 15-51 
length of entry ® 15-55 
name of record-address file ® 15-51 
name of table input file ® 15-51 
number of entries per record ® 15-54 
number of entries per table or array ® 15-55 
sequence ® 15-58 
table or array name ® 15-53 
to file name ® 15-52 
type ® 15-51 
External indicators ® 7-18 
controlling the opening of files ® 7-18 
example ® 7-18, 12-30 
function ® 7-18 
setting ® 7-18 
specifying ® 7-18 
EXTRN operation code ® 16-32 
accessing 
link-time constants ® 16-32 
VAX/VMS Run-Time Library status codes 
® 16-33 
example ® 16-36 
rules ® 16-32 


F 


Factor 1® 15-104 
Factor 2® 15-104 
Fetch overflow ® 9-12, 15-119 
example ® 9-13, 15-120 
rules for specifying ® 9-13, 15-119 
FIELD_BACKWARD function ® 2-34 
example ® 2-68 
FIELD_FORWARD function ® 2-35 
FIELD function ® 2-28 
example ® 2-28 
Field indicators ® 7-4 
checking the condition of data fields ® 15-97 
conditioning input data ® 15-97 


Field indicators (cont’d.) 
example ® 7-5 
function ® 7-4 
rules for specifying ® 15-97 
Field length ® 15-108 
rules for specifying® 15-108 
Field locations ® 15-80 
rules for specifying ® 15-80 
Field name ® 15-81, 15-126 
Input specification * 15-81 
example ® 15-82 
rules for specifying ® 15-81 
Output specification ® 15-126 
example ® 15-127 
rules for specifying ® 15-126 
Field names ® 14-8 
Field-record-relation indicators ® 15-94 
conditioning input data ® 15-94 
controlling data extraction ® 15-94 
example ® 15-96 
rules for specifying ® 15-95 
using matching fields ® 8-38 
example ® 8-38, 8-39 
Fields 
common ® 15-4 
defining locations ® 15-80 . 
indicators ® 7-4 
input 
specifying 
decimal positions ® 15-81 
look-ahead ® 15-73 
matching ® 8-35, 15-92 
checking sequence ® 15-24 
naming ® 15-81 
repeating ® 9-9 
specifying 
data format ® 15-79 
IN® 15-81 
IN. xx ® 15-81 
length ® 15-108 
PAGE special word ® 15-81 
split-control ® 7-12 
testing values ® 7-4 
that require 
blanks ® 15-2 
character values ® 15-2 
numeric values ® 15-3 
using indicators to compare contents ® 15-90 
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File access methods ® 8-6 
random ® 8-14 
sequential ® 8-8 
sequential by key ® 8-9 
sequential within limits © 8-10 
table ® 8-7 
File addition ® 15-42 
rules for specifying ® 15-43 
File buffers ® 8-49 
File condition ® 15-47 
File Description specification ® 15-19 
additional |/O area ® 15-36 
block length ® 15-26 
core index ® 15-41 
device code ® 15-38 
end-of-file * 15-24 
example ® 15-48 
expansion factor ® 15-43 
extension code ® 15-37 
file addition ® 15-42 
file condition ® 15-47 
file designation ® 15-22 
file format ® 15-25 
file name ® 15-20 
file organization ® 15-36 
file sharing ® 15-45 
file type ® 15-21 
format ® 15-20 
F spec continuation lines ® 15-40 
key length ® 15-34 
key location ® 15-37 
mode of processing ® 15-28 
overflow indicators ® 15-36 
record address type ® 15-35 
record length ® 15-28 
sequence ® 15-24 
symbolic device ® 15-39 
tape label ® 15-40 
tape rewind ® 15-47 
type ® 15-20 
unordered output ® 15-42 
File designations ® 15-22 
array ® 15-22 
chained ® 15-22 
demand ® 15-22 
full-procedural ® 15-22 
primary ® 15-22 © 
record-address ® 15-22 
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File designations (cont’d.) 


secondary ® 15-22 
table ® 15-22 


File format ® 15-25 


rules for specifying ® 15-25 


File names ® 14-8 


File Description specification ® 15-20 
rules for specifying ® 15-21 
Input specification © 15-66 
rules for specifying ® 15-66 
Line Counter specification ® 15-62 
rules for specifying ® 15-62 
Output specification ® 15-114 
rules for specifying ® 15-114 
rules for specifying ® 8-2 


File organizations ® 15-36 — 


direct ® 8-4 
indexed ® 8-5 
sequential ® 8-4 


Files 


adding records ® 8-27 
ADDROUT ® 8-17 

‘specifying 

key length ® 15-34 

CHAIN operation code ® 16-17 
changing processing order ® 16-22 
characteristics ® 8-1 
compiler listing © 4-1 
conditioning. with an external indicator © 15-47 
creating ® 8-24 

ADDROUT ® 8-18 

direct ® 8-25 

indexed ® 8-26 

output ® 9-1 

printer output ® 9-1 

record-limits © 8-10 

sequential ® 8-24 
definition ® 8-1 
deleting records ® 8-34 
DSPLY operation code ® 16-19 
EXCPT operation code ® 16-21 
external indicators ® 7-18 
file access methods ® 8-6 
file names ® 8-2 
file types ® 8-3 
FORCE operation code ® 16-22 
full-procedural ® 8-2 1 

example ® 8-23 ° 


Files (cont’d.) 
improving search efficiency ® 15-43 
indexed 
specifying 
key length ® 15-34 
input 
specifying 
file addition ® 15-42 
unordered output ® 15-42 
input/output operation codes ® 16-17 
matching-record indicators ® 7-18 
multifile processing ® 8-40 
organization ® 8-3 
output ® 9-1 
controlling overflow ® 15-36 
using overflow indicators ® 15-36 
performance optimizing ® 15-26 
preventing bucket splitting ® 15-43 
primary WORKSTN ® 6-6 
printer output ® 9-1 
controlling overflow ® 15-36 
using overflow indicators ® 15-36 
processing using matching fields ® 15-92 
random access ® 8-14 
random access by key ® 8-16 
reading record during calculations ® 16-17 
READ operation code ® 16-23 
record formats ® 8-3 
record-limits ® 8-10 © 
specifying 
key length ® 15-34 
sequential access ® 8-8, 8-21 
sequential by key access ® 8-9 
sequential within limits access ® 8-10 
SETLL operation code ® 16-24 
specifications ® 6-4 
specifying 
chained ® 15-22 
demand ® 15-22 
display ® 15-21 
full-procedural © 15-22 
input ® 15-21 
mode of processing ® 15-28 
output ® 15-21 . 
primary ® 15-22 
record-address ® 15-22 
secondary ® 15-22 
update ® 15-21 


Files (cont’d.) 
update 
specifying 
file addition ® 15-42 
unordered output ® 15-42 
updating records ® 8-31 
WORKSTN ® 6-3 
File sharing ® 15-45 
rules for specifying ® 15-45 
File types ® 15-21 
display ® 15-21 
input ® 8-3, 15-21 
output ® 8-3, 15-21 
update ® 8-3, 15-21 
FIND_NEXT function ® 2-20 
example ® 2-80 
FIND function ® 2-20 
example ® 2-78 
First cycle ® 1-6 
First-page indicators ® 7-15, 9-11 
conditioning output data ® 7-15 
example ® 7-16 
function ® 7-15 
specifying ® 7-15 
FL® 15-63 
FMS ® 12-33, 12-36 
FMTS 
name ® 6-4 
FORCE operation code ® 16-22 
changing file processing order ® 16-22 
example ® 16-23 
rules © 16-22 
selecting files ® 16-22 
Form ® 15-132 
creation ® 6-2 
libraries ® 6-3 
modification ® 6-2 
terminators ® 6-11 
Form length ® 15-62 
FL® 15-63 
rules for specifying ® 15-62 
Form names ® 15-137 
Forms alignment 
changing ® 15-17 
Forms library name ® 15-18 
Forms position ® 15-17 
From file name 
arrays ® 15-51 
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From file name (cont’d.) 


record-address files ® 15-51 
rules for specifying ® 15-52 
tables ® 15-51 
F specification 
INFDS clause ® 6-15 
Function calls 
for system routines ® 12-17 
Function keys ® 6-10 . 
defining a UAR® 6-13 
form terminators ® 6-11 
Functions ® 2-12 
ADVANCE ® 2-25 
BACKUP ® 2-25 
BOTTOM ® 2-25 
CHARACTER ® 2-31 
COLUMN ® 2-32 
COMMAND ® 2-22 
CUT ® 2-26 
DELETE_CHARACTER ® 2-34 
DELETE_FIELD ® 2-24 
DELETE_LINE ® 2-21 
DELETE __TO_BEGINNING_OF_LINE ® 2-35 
DELETE_TO_END_OF_LINE ® 2-30 
DISPLAY ® 2-23 
displaying specification formats ® 2-17 
DOWN ® 2-33 
END_OF_LINE ® 2-29 
ENTER ® 2-32 
executing editor commands ® 2-22 
EXIT ® 2-35 
FIELD ® 2-28 
FIELD_BACKWARD ® 2-34 
FIELD_FORWARD ® 2-35 
FIND ® 2-20 
specifying the search string ® 2-20 
FIND_NEXT ® 2-20 
finding the next occurrence of the search 
string ® 2-20 
GOLD ® 2-15 
HELP_KEYPAD ® 2-15 
HELP_SPECIFICATIONS ® 2-17 
LEFT ® 2-34 
LINE ® 2-32 
MOVE_TO_RULER ® 2-24 
NEW_LINE ® 2-34 
OPEN_LINE ® 2-32 
PAGE ® 2-21 
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Functions (cont’d.) 


paging through the source file ® 2-21 
PASTE ® 2-26 

REFRESH_SCREEN ® 2-35 

RESET ® 2-33 

REVIEW_ERROR ® 2-23 

RIGHT ® 2-34 

SECTION ® 2-23 

SELECT ® 2-33 

selecting alternate functions ® 2-15 
SHIFT_LEFT ® 2-26 

SHIFT_RIGHT ® 2-27 

table ® 2-12 

TOP ® 2-25 

UNDELETE_FIELD ® 2-24 
UNDELETE_LINE ® 2-21 

UP ® 2-33 

VAX RPG II editor ® 2-12 


General logic cycle ® 1-5 
GIVNG operation code ® 16-33 
retrieving VAX/VMS Run-Time Library return 
status ® 16-33 
rules ® 16-33 
GOLD function ® 2-15 
GOTO operation code ® 16-25 
example ® 16-27 
rules ® 16-26 


Half adjust © 15-109 
rules for specifying ® 15-110 
using resulting indicators ® 16-32 
Halt indicators ® 7-19 
controlling program execution ® 7-19 
example ® 7-19, 7-20 
function ® 7-19 
handling errors ® 7-19 
HELP_KEYPAD function ® 2-15 
displaying HELP information on key functions ® 
2-17 
example ® 2-16 


HELP_SPECIFICATIONS function ® 2-17 
displaying specification formats 
example® 2-18 
HELP_SPECS function 
example ® 2-66 
HELP option ® 2-51 
HELP window ® 2-6 
definition ® 2-7 
displaying HELP information ® 2-7 
Hexadecimal character set ® A- 1 
H specification ® 6-4 


1/O areas 
specifying 
additional areas ® 15-36 
IDENT field 
values ® 3-13 
Indexed file organization ® 8-5 
example ® 8-5 
index key ® 8-5 
example ® 8-6 
Indexed files 
adding records ® 8-31 
example ® 8-31 
rules for specifying ® 8-31 
creating ® 8-26 
example ® 8-27 
rules for specifying ® 8-26 
specifying 
addition of records ® 15-42 
Key length ® 15-34 
Key location ® 15-37 
updating records 
rules for specifying ® 8-33 
Indicators ® 7-1 
IN® 7-22 
IN,n® 7-22 
INxx ® 7-23 
Calculation specification ® 15-101 
example ® 15-104 
conditioning — 
calculations ® 15-101 
output ® 15-123 
control-level ® 7-9, 15-90, 15-99 
external ® 7-18 


Indicators (cont'd.) 


field ® 7-4, 15-97 
field-record-relation ® 15-94 
first-page ® 7-15, 9-11 
function ® 7-1 
halt © 7-19, 7-20 
internally defined ® 7-15 
K°e6-11 
last-record © 7-17 
matching-record ® 7-18 
negating ® 15-101 
Output specification 

example ® 15-126 

rules for specifying © 15-124 
overflow ® 7-12, 9-11, 15-36 - 
1P®7-15, 9-11 
printer output files ® 9-11 
read only ® 16-34 
record-identifying ® 7-2, 15-72 
resulting ® 7-6, 15-110 
setting off ® 16-11 
setting on® 16-10 
usage ® 7-1 
user-defined ® 7-1 
using as fields ® 7-22 
write only ® 16-34 


INFDS 


*FMSSTA ® 6-18 
*FMSTER ® 6-18 
*OPCODE ® 6-17 
*RECORD ® 6-18 
*STATUS ® 6-17 
WORKSTN file operations ® 6-15 


Input/output operation codes ® 16-17 


CHAIN ® 16-17 
DSPLY © 16-19 
EXCPT © 16-21 
FORCE ® 16-22 
READ ® 16-23 

SETLL® 16-24 


Input files 


selecting mode of processing ® 15-29 
specifying 

file addition ® 15-42 

unordered output ® 15-42 


Input specification ® 15-65 


AND ® 15-77 
character ® 15-76 
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Input specification (cont’d.) 
control-level indicators ® 15-90 
COPY_CDD ® 15-7 
copy modifiers ® 15-9 
CZD portion® 15-76 
data format ® 15-79 
data structure ® 15-65 
data structures ® 15-67 
data structures 
examples ® 15-83, 15-84, 15-85, 15-86 
decimal positions ® 15-81 
field indicators ® 15-97 
field locations ® 15-80 
field name ® 15-81 
field-record-relation indicators ® 15-94 
file name ® 15-66 
format ® 15-65 
identifying record types ® 15-72 
matching fields ® 15-92 
not ® 15-75 
number ® 15-71 
optional ® 15-72 
OR ® 15-77 
position ® 15-75 
record identification codes ® 15-74 
record-identifying indicators ® 15-72 
sequence ® 15-71 
specifying 
alphabetic sequence code ® 15-71 
data formats ® 15-79 
data structure statement ® 15-67 
data structure subfield ® 15-68 
file names 
example ® 15-67 
input file names ® 15-66 
look-ahead fields ® 15-73 
numeric sequence code ® 15-71 
record identification codes ® 15-74 
sequence code ® 15-71 
update file names ® 15-66 
type ® 15-65 
Input specifications — 
WORKSTN ® 6-5 
INTO ®5-12 
Inverted print ® 15-14 
! specification ® 6-15 
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JOURNAL qualifier © 2-4 


Key length 
ADDROUT files ® 15-34 
example ® 15-35 
Indexed files ® 15-34 
record-limits files © 15-34 
rules for specifying ® 15-34 
Key location ® 15-37 
rules for specifying ® 15-37 
Keypad ® 2-12 
Keys 
command ® 6-1 
function ® 6-10 
K indicators ® 6-10, 6-11, 7-13 
example ® 7-13 





L 


Label names ® 14-8 
Language elements ® 14-1 
Last cycle ® 1-7 
Last-record indicators ® 7-17 
example ® 7-17 
function ® 7-17 
totaling data ® 7-17 
LEFT function ® 2-34 
Length of entry ® 15-55 
arrays ® 15-55 
rules for specifying ® 15-55 
tables ® 15-55 
Library 
form ® 6-3 
multiple forms ® 6-3 
LINE © 5-12 
Line Counter specification ® 15-61 
example ® 15-64 
file name ® 15-62 
FL® 15-63 
format ® 15-61 
form length ® 15-62 
naming the output file © 15-62 


Line Counter specification (cont'd.) 
OL ® 15-64 
overflow line number ® 15-63 
type ® 15-61 
LINE function ® 2-32 
example ® 2-84 
Line numbers ® 15-4 
checking ® 3-10, 15-4 
Line relationships 
AND ® 15-77 
OR ® 15-77 
LINK command ® 3-11 
example ® 3-12 
format ® 3-11 
Linking 
object file with UAR ® 6-14 
Linking programs ® 3-11 
List, appended ® 3-3 
LIST ® 3-3 
Listing file 
generating ® 3-8 
LIST qualifier © 3-8 
format ® 3-8 
generating a listing file ® 3-3, 3-8, 4-1 
including cross-reference information ® 3-8 
including machine code ® 3-8 
Local data area ® 15-70 
examples ® 15-88 
Logic cycle ® 1-1 
detail time ® 1-9 
characteristics and operations ® 1-5 
flowchart ® 1-10 
general ® 1-5 
look-ahead processing ® 1-22 
matching-fields routine ® 1-18 
normal cycle ® 1-7 
overflow processing ® 1-21 
processing chained and demand files ® 1-20 
steps of 
a normal cycle ® 1-7 
the first cycle ® 1-6 
the last cycle ® 1-7 
the first cycle ® 1-6 
the last cycle ® 1-7 
total time ® 1-8 
characteristics and operations ® 1-5 
LOKUP operation code ® 16-27 
arrays ® 11-17 


LOKUP operation code 
arrays (cont’d.) 
example ® 11-19 
example ® 16-30, 16-31 
referencing entries ® 10-9 
searching 
arrays ® 16-30 
related tables ® 16-28 
tables ® 10-10, 16-28 
specifying array elements ® 16-30 
Long character literals ® 15-137 
Longword binary data type 
example ® 14-4 
Look-ahead fields ® 15-73 
example ® 15-73 
function ® 15-73 
logic cycle ® 1-22 
flowchart ® 1-22 
rules for specifying ® 15-73 
LR indicators ® 7-17 


MACHINE_CODE qualifier © 3-9 
format ® 3-9 
generating machine code ® 3-9, 4-8 
Magnetic tape device 
specifying ® 15-38 
Magnetic tapes 
rewinding ® 15-47 
Manual conversion ® 6-30 
line 24 ® 6-31 
Matching fields ® 15-92 
checking record sequence ® 8-35, 15-24 
example ® 8-36 
for more than one record type ® 8-35 
example ® 8-36 
logic cycle ® 1-18 
flowchart ® 1-18 
multifile processing ® 8-35, 8-40 
example ® 8-46 
figure ® 8-42 to 8-44 
record selection ® 8-40, 8-45 to 8-46 
rules for specifying ® 8-40 
tables ® 8-41, 8-47 to 8-48 
rules for specifying ® 15-92 
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Matching fields (cont’d.) 
using with field-record-relation indicators ® 8-38 
example ® 8-38, 8-39 
Matching-record indicators ® 7-18 
function ® 7-18 
multifile processing ® 7-18 
Message line ® 2-6 
definition © 2-9 
example ® 2-8 
Mode of processing ® 15-28 
example ® 15-34 
loading a direct file ® 15-28 
rules for specifying ® 15-28 
selecting ® 15-29 
specifying 
access 
random ® 15-28 
sequential ® 15-28 
sequential within limits © 15-28 
an ADDROUT file ® 15-28 
record address type ® 15-35 
Modular Programming Standard ® 12-32 
MOVE_TO_RULER function ® 2-24 
MOVEA operation code ® 16-7 
arrays ® 11-21 
example ® 11-22, 16-9 
_tules © 16-7 
MOVEL operation code ® 16-8 
example ® 16-9 
rules ® 16-8 
MOVE operation code ® 16-6 
example ® 16-9 
rules ® 16-7 
Move operation codes ® 16-6 
example ® 16-9 
MOVE ® 16-6 
MOVEA ® 16-7 
MOVEL® 16-8 
Multifile processing ® 8-40 
checking record sequence ® 8-35 
example ® 8-36 
for more than one record types ® 8-35 
matching fields © 8-35 
using . 
matching fields ® 8-35 
matching-record indicators ® 7-18, 8-35 
MR indicators ® 8-35 
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Multiple keys ® 8-48 
Multiplication operation ® 16-3 
MULT operation code ® 16-3 
example ® 16-5 
MVR operation code ® 16-4 
example ® 16-5 
saving the remainder ® 16-4 


Named data item ® 6-14 
Names 
arrays ® 14-8 
specifying ® 15-53 
EXCPT ® 14-8 
fields © 14-8 
files © 14-8 
labels ® 14-8 
PLIST ® 14-8 
subroutines ® 14-8 
tables ® 14-8 
specifying ® 15-53 
user-defined ® 14-8 
NEW_LINE function ® 2-34 
Normal cycle ® 1-7 
Not 
see record identification codes 
Notations 
edit codes ® 15-14 
numeric fields ® 15-14 
UDATE ® 15-14 
Number ® 15-71 
rules for specifying ® 15-71 
Number of entries per record ® 15-54 
arrays ® 15-54 
rules for specifying ® 15-54 
tables ® 15-54 
Number of entries per table or array ® 15-55 
rules for specifying ® 15-55 
Numeric data 
specifying 
format ® 15-134 
Numeric fields 
editing ® 15-138 
example ® 15-3 
rounding ® 15-109 


Numeric fields (cont'd.) 
specifying 
notation ® 15-14 
Numeric sequence code ® 15-72 


OBJECT qualifier ® 3-9 
format ® 3-9 
generating an object module ® 3-9 
rules ® 3-9 
specifying an output file ® 3-10 
OL ® 15-64 
OPEN _LINE function ® 2-32 
Operation codes ® 16-1 
arithmetic ® 16-1 
ADD ® 16-3 
DIV ® 16-4 
MULT ® 16-3 
MVR ® 16-4 
SORT ® 16-4 
SUB ® 16-3 
XFOOT ® 16-5 
Z-ADD ® 16-3 
Z-SUB ® 16-3 
bit ® 16-13 
BITOF ® 16-14 
BITON ® 16-13 
TESTB ® 16-14 
branching ® 16-25 
example ® 16-27 
GOTO ® 16-25 
TAG ® 16-26 
compare ® 16-16 
COMP ® 16-16 
input/output ® 16-17 
CHAIN ® 16-17 
DSPLY ® 16-19 
EXCPT ® 15-127, 16-21 
FORCE ® 16-22 
READ ® 16-23 
SETLL ® 16-24 
LOKUP ® 16-27 
move ® 16-6 
MOVE ® 16-6 
MOVEA ® 16-7 
MOVEL ® 16-8 





Operation codes (cont'd.) 
SET ® 16-10 
SETON ® 16-10 
SETOF ® 16-11 
specifying ® 15-107 
subprogram ® 16-31 
CALL ® 16-32 
EXTRN ® 16-32 
GIVNG ® 16-33 
PARM ® 16-33 
PARMD ® 16-34 
PARMV ® 16-35 
PLIST ® 16-35 
subroutine ® 16-11 
BEGSR ® 16-12 
ENDSR ® 16-12 
EXSR ® 16-12 
summary 
table.* 16-38 
TIME ® 16-36 
Optimizing 
file performance ® 15-26, 15-41 
Optimizing programs ® 13-1 
asterisk indicator ® 13-3 
expansion factor ® 13-4 
file applications ® 13-4 
file performance ® 13-4 
file sharing ® 13-4 
1/O processing ® 13-4 
multiblock count ® 13-4 
multibuffer count ® 13-4 
multiple C specifications ® 13-3 
with adjacent fields ® 13-3 
with blank factor 1® 13-3 
with data structures ® 13-1 
Optional ® 15-72 
rules for specifying ® 15-72 
OR ® 15-77, 15-114 
example ® 15-78 
Output specification 
example ® 15-115 
rules for specifying ® 15-78, 15-114 
Output files 
controlling overflow ® 15-36 
specifying 
file addition ® 15-42 
file name ® 15-62 
unordered output ® 15-42 
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Output files (cont’d.) 
using overflow indicators ® 15-36 
OUTPUT qualifier © 2-4 
Output specification ® 15-113 
AND ® 15-114 
blank after ® 15-131 
constants 
long character literals ® 15-137 
COPY_CDD ® 15-7 
data format ® 15-134 
edit code modifiers ® 15-135 
edit codes ® 15-128 
edit words ® 15-138 
end position ® 15-132 
fetch overflow ® 15-119 
field name ® 15-126 
file name ® 15-114 
format ® 15-113 
form names ® 15-137 
function ® 15-113 
indicators ® 15-123 
OR ® 15-114 
record type ® 15-116 
skip after ® 15-121 
skip before ® 15-121 
space after® 15-120 
space before ® 15-120 
specifying 
ADD option ® 15-118 
DEL option ® 15-118 
type ® 15-113 
Output specifications 
WORKSTN files ® 6-7 
OVER ® 5-12 
Overflow 
automatic ® 9-15 
Overflow indicators ® 7-12, 9-11, 15-36 
causing page breaks ® 7-12 
example ® 7-13, 9-14 
function ® 7-12 
rules for specifying ® 9-11, 15-36 
specifying ® 7-12 
Fetch overflow ® 15-119 
Overflow line number ® 15-63 
OL ® 15-64 
rules for specifying ® 15-63 
Overflow processing 
logic cycle ® 1-21 
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Overflow processing 
logic cycle (cont’d.) 
flowchart ® 1-21 
Overpunched decimal! 
specifying ® 15-56 
Overpunched decimal data type 
example ® 14-7 
representation of all but the least significant 
digits ® 14-5 
representation of least significant digits and 
signs ® 14-6 
trailing numeric string ® 14-7 


Packed decimal data type 
example ® 14-5 
specifying ® 15-56 
PAGE1 special word ® 9-6 
PAGE2 special word ® 9-6 
PAGE3 special word ® 9-6 
PAGE4 special word ® 9-6 
PAGE5 special word ® 9-6 
PAGE6 special word ® 9-6 
PAGE7 special word ® 9-6 
PAGE function ® 2-21 
example ® 2-2 1 
Page size 
defining ® 9-15 
PAGE special word ® 9-6 
changing the page number ® 9-7 
example ® 9-7 
resetting the page number ® 9-8 
Paging special words 
rules for specifying ® 9-6 
Parameters 
list ® 16-35 
passing 
access types ® 16-34 
data types ® 16-34 
mechanisms ® 16-34 
by descriptor ® 16-34 
by reference ® 16-33 
by value ® 16-35 
PARM 
operation code ® 16-33 
example ® 12-8 


PARM 
operation code (cont’d.) 
rules © 16-33 
PARMD 
operation code ® 16-34 
example ® 16-36 
rules ® 16-35 
PARMD operation code 
example ® 12-13 
PARM operation code 
example ® 12-13 
PARMV 
operation code ® 16-35 
example ® 12-12 
PARMV operation code 
example ® 12-19 
rules © 16-35 
Passing mechanisms ® 12-13 
Paste buffer®2-11 | 
PASTE function ® 2-26 
example ® 2-85 
PDP-11 RPG Il 
See also VAX RPG II ®B-1 
comparison with VAX RPG Il®B-1 
1P indicators ® 7-15, 9-11 
conditioriing output data ® 7-15 
example ® 7-16 | 
function ® 7-15 
specifying ® 7-15 
*PLACE special word ® 9-9 
example ® 9-10 
rules for specifying ® 9-9 
PLIST 
names ® 14-8 
operation code ® 16-35 
rules ® 16-35 
Plus list ® 3-4, 15-7 
Position 
see record identification codes 
rules for specifying ® 15-75 
Preexecution-time arrays ® 11-4 
creating ® 11-4, 11-8 
rules for specifying ® 11-4 
outputting ® 11-23 
searching 
example ® 11-20 
updating ® 11-22 
writing ® 11-23 


Preexecution-time tables ® 10-3 


creating 
example ® 10-8 
outputting ® 10-13 
rules for defining ® 10-8 
updating ® 10-12 
example ® 10-13 
writing ® 10-14 


Primary files 


selecting mode of processing ® 15-29 


Primary WORKSTN file ® 6-6 
Printer device 


specifying ® 15-38 


Printer output files © 9-1 


automatic overflow ® 9-15 
changing page numbers ® 9-6 
checking the alignment ® 15-17 
conditioning output ® 9-10 
constants 

example ® 9-3 
controlling overflow ® 15-36 
creating ® 9-1 
defining 

page numbers ® 9-6 

page size ® 9-15 

rules for specifying ® 9-16 

deleting form-feed characters ® 9-1 
editing 

numeric data® 15-138 
editing output ® 9-2, 15-128 
first-page indicators ® 7-15 
formatting ® 15-120, 15-121 

output ® 9-16 

output data ® 15-132, 15-135 
generating report titles ® 15-137 
last-record indicators ® 7-17 
NOFEED qualifier © 9-1 
overflow indicators 


using ® 7-12 
paging ® 9-6 © 
1P indicators ® 7-15 
printing 


IMPORTANT INFORMATION ® 9-1 
printing the date ® 9-4 
repeating output records ® 9-9 
resetting page numbers ® 9-6 
skip entries ® 9-16 
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Printer output files 
skip entries (cont’d.) 
example ® 9-18 
space entries ® 9-16 
example ® 9-18 
specifying 
a negative sign ® 15-143 
asterisks ® 15-140 
blank spaces ® 15-140 
commas ® 15-141 
constant data ® 15-137 
CR® 15-143 
currency symbol ® 15-140 
decimal points ® 15-141 
fetch overflow ® 15-119 
overflow line number ® 15-63 
page breaks ® 9-11 
page numbers ® 9-6 
page size ® 15-62 
skip after ® 15-121 
skip before ® 15-121 
space after ® 15-120 
space before ® 15-120 
zero-suppression ® 15-139 
using 
constants ® 9-3 
edit code modifiers ® 9-2 
asterisk fill © 9-2 
floating dollar sign ® 9-2 
edit codes ® 9-2 
first-page indicators ® 9-11 
indicators to condition output ® 15-123 
overflow indicators ® 9-11, 15-36 
example ® 9-13 
1P indicators ® 9-11 
special words ® 9-4 
Procedure Calling and Condition Handling Standard 
® 12-32 
Procedure calls ® 12-20 
Processing 
branching ® 16-25 
files 
chained 
flowchart ® 1-20 
demand 
flowchart ® 1-20 
specifying 
an ADDROUT file ® 15-28 
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Processing 
files 
specifying (cont’d.) 
random access ® 15-28 
sequential access ® 15-28 
sequential within limits access ® 15-28 
look-ahead fields 
flowchart ® 1-22 
multifiles © 8-40 
Processing files 
multiple keys ® 8-48 
example ® 8-49 
Program conversion 
HALT indicators ® 7-21 
Program development ® 3-1 
compiling ® 3-1 
linking ® 3-11 
running ® 3-12 
Program development cycle ® 6-19 
Programs 
See also VAX RPG II programs 
branching ® 16-25 
developing ® 3-1 
logic cycle ® 1-1 
Prompt line ® 2-6 
definition ® 2-9 


Qualifiers 
debugger ® 5-2 
RPG/EDIT command ® 2-3 
RPG command ® 3-3 


Random by ADDROUT file access ® 8-17 
example ® 8-2 1 
rules for specifying ® 8-19 
Random by key file access ® 8-16 
example ® 8-17 
rules for specifying ® 8-16 
Random file access ® 8-14 
using 
an ADDROUT file © 8-17 
keys ® 8-16 





Random file access 
using (cont’d.) 
relative record numbers ® 8-14 
example ® 8-15 
rules for specifying ® 8-14 
READ_ONLY qualifier ® 2-5 
READ operation code ® 16-23 
demand files ® 16-24 
example ® 16-24 
full-procedural files © 16-23 
rules ® 16-23 
Record-address files 
selecting mode of processing ® 15-32 
specifying 
from file name ® 15-51 
to file name ® 15-52 
Record address type ® 15-35 
Record buffer layout ® 6-31 
Record formats 
fixed ® 8-3 
variable ® 8-3 
Record identification codes ® 15-74 
identifying record types ® 15-74 
specifying 
character ® 15-76 
CZD portion ® 15-76 
example ® 15-76 
not ® 15-75 
position ® 15-75 
Record-identifying indicators ® 15-72 
conditioning input data ® 15-72 
example ® 7-2, 7-3 
function ® 7-2 
_ identifying record types ® 7-2 
Record length ® 15-28 
rules for specifying ® 15-25, 15-28 
Record-limits files 
example ® 8-10 
function ® 8-11 
rules for specifying ® 8-11 
specifying 
key length ® 15-34 
Records 
adding ® 8-27, 15-118 
array input @ 11-4 
changing processing order ® 16-23 
deleting ® 8-34, 15-118 
example ® 8-34 


Records (cont'd.) 
general processing cycle ® 1-5 
identifying types ® 15-72 
processing totals ® 1-8 
record-identifying indicators ® 7-2 
selecting 
SETLL operation code ® 16-24 
specifying 
detail ® 15-116 
exception ® 15-116 
format ® 15-25 
heading ® 15-116 
length 
fixed ® 15-25 
variable ® 15-25 
record identification codes ® 15-74 
total ® 15-116 
types ® 15-116 
defining the ordering sequence ® 15-71 
updating ® 8-31 
example ® 8-33 
using record-identifying indicators ® 7-2 
writing during calculations ® 16-21 
Record types ® 15-116 
defining the ordering sequence ® 15-71 
detail ® 15-116 
example ® 15-116 
exception ® 15-116 
heading ® 15-116 
identifying ® 15-72 
rules for specifying ® 15-116 
specifying 
record identification codes ® 15-74 
total ® 15-116 
using record-identifying indicators ® 7-2 
RECOVER qualifier ® 2-5 
REFRESH_SCREEN ® 2-35 
Related arrays ® 11-5 
alternate format ® 11-10 
creating ® 11-5, 11-10 
Related tables 
alternate format 
example ® 10-12 
creating ® 10-4 
example ® 10-7 
input records ® 10-4 
entries 
example ® 10-4 
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LOKUP operation code 
rules ® 16-28 
updating ® 10-13 
RESET function ® 2-33 
Result field ® 15-107 
rounding data ® 15-109 
rules for specifying ® 15-107 
Resulting indicators ® 7-6, 15-110 
arrays ® 11-18 
example ® 7-8 
function ® 7-6 
rules for specifying ® 15-111 
specifying 
result of search @ 16-28 
type of search ® 16-28 
testing calculation results ® 7-6 
types of tests ® 7-6 
using half adjust ® 16-32 
RETURN key 
example ® 2-67 
REVIEW_ERROR function ® 2-23 
RIGHT function ® 2-34 
example ® 2-66 
RPG/DEBUG ® 5-1 
RPG/EDIT command ® 2-1 
qualifiers 
/COMMAND ® 2-3 
/CREATE ® 2-4 
/JOURNAL ® 2-4 
/OUTPUT ® 2-4 
/READ_ONLY ® 2-5 
/RECOVER ® 2-5 
/START_POSITION ® 2-6 
table ® 2-3 
RPG command 
appended list ® 3-4 
defining as a symbol ® 3-3 
format ® 3-1 
plus list © 3-4 
qualifiers ® 3-3 
CHECK ® 3-6 
CROSS_REFERENCE ® 3-7 
DEBUG ® 3-7 
example ® 3-3, 3-4 
format ® 3-3 
LIST @ 3-8 
MACHINE__CODE ® 3-9 
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RPG command 
qualifiers (cont'd.) 
negating ® 3-3 
OBJECT ® 3-9 
SEQUENCE_CHECK ® 3-10 
table®3-4 — 
WARNINGS ® 3-10 
RPG I! programs 
arrays ® 11-1 
calling 
subprograms ® 12-32 
system services ® 12-28 
call interface ® 12-1 
documenting ® 15-5 
logic cycle ® 1-1 
RPG I! specifications ® 15-1 
Ruler ® 2-6 
RULER option ® 2-51 
RUN command ® 3-12 
example ® 3-12 
format ® 3-12 
Running programs ® 3-12 
Run-Time Library routines ® 12-2 
example of calling ® 12-25 
facilities © 12-2 
how to call® 12-4 
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Screen handling ® 6-1, 12-33 
SMG$ ® 12-36 
example ® 12-37 
TDMS 
example ® 12-34, 12-35 
VAX FMS ® 12-33, 12-36 
example ® 12-36 
VAX SMG$ ® 12-33 
VAX TDMS ® 12-33 
SCROLL option ® 2-53 
Secondary files 
selecting mode of processing ® 15-29 
SECTION function ® 2-23 
SECTION option ® 2-54 
SELECT function ® 2-33 
example ® 2-85 
SEQUENCE _CHECK qualifier © 3-10 
checking line number sequence ® a4 


SEQUENCE_CHECK qualifier (cont’d.) 
format ® 3-10 
Sequence codes ® 15-24, 15-58, 15-71 
assigning a numeric code ® 15-71 
number ® 15-71 
rules for specifying ® 15-25, 15-58 
specifying 
alphabetic ® 15-71 
continued processing ® 15-72 
numeric ® 15-71 
Sequential by key file access 
example ® 8-10 
rules for specifying ® 8-9 
Sequential file access ® 8-8 
example ® 8-8 
rules for specifying ® 8-8 
Sequential file organization ® 8-4 
example ® 8-4 
Sequential files 
adding records ® 8-28 
example ® 8-29 
figure ® 8-28 
rules for specifying ® 8-28 
creating ® 8-24 
example ® 8-24 
rules for specifying ® 8-24 
Sequential within limits file access 
example ® 8-12 
record-limits file © 8-10 
SET command ® 2-50 
COMMAND option ® 2-50 
DEFAULT option ® 2-51 
HELP option ® 2-51 
RULER option ® 2-51 
SCROLL option ® 2-53 
SECTION option ® 2-54 
STARTCOLUMN option ® 2-54 
SYNTAXCHECK option ® 2-55 
SET COMMAND option ® 2-50 
SETLL operation code ® 16-24 
example ® 16-25 
rules ® 16-24 
selecting the next record ® 16-24 
SETOF operation code ® 16-11 
example ® 16-11 
rules ® 16-11 
SETON operation code ® 16-10 
example ® 16-11 


SETON operation code (cont'd.) 
rules ® 16-10 
SET operation codes ® 16-10 
SETON ® 16-10 
example ® 16-11 
SHIFT_LEFT function ® 2-26 
example ® 2-26 
SHIFT_RIGHT function ® 2-27 
“example ® 2-27 
Skip after ® 15-121 
example ® 15-123 
rules for specifying ® 15-122 
Skip before ® 15-121 
example ® 15-123 
rules for specifying ® 15-122 
SMG$ ® 12-33, 12-36 to 12-37 
SOURCE ® 5-12 
Space after ® 15-120 
rules for specifying ® 15-121 
Space before ® 15-120 
rules for specifying ® 15-121 
Special words ® 9-4 
PAGE ® 9-6 
PAGE1 ® 9-6 
PAGE2 ® 9-6 
PAGE3 ® 9-6 
PAGE4 ® 9-6 
PAGE5 ® 9-6 
PAGE6 ® 9-6 
PAGE7 © 9-6 
paging ® 9-6 
*PLACE ®9-9 
rules for specifying ® 9-5 
UDATE ® 9-4 
UDAY 
example ® 9-5 
UMONTH 
example ® 9-5 
UYEAR 
example ® 9-5 
Specification format 
asterisks ® 15-2 
column numbers ® 15-2 
comments ® 15-5 
dashes ® 15-3 
dots ® 15-2 
line number ® 15-4 
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Specification format (cont’d.) 
notational conventions ® 15-2 
Specifications 
C°6-16 
Calculation ® 15-98 
Control ® 15-13 
D®6-29 
Extension ® 15-50 
Fe6-15 
File Description ® 15-19 
format ® 15-2 
He 6-4 
1¢6-15 
Input © 15-65 
Line Counter ® 15-61 
. Output ® 15-113 
RPG tl®@ 15-1 
S°6-27 
S and D® 6-25 
conversion utility ® 6-25 
types ® 15-4 
Split-control fields 
example ® 7-12 
SORT operation code ® 16-4 
example ® 16-5 
Square root operation ® 16-4 
S specification ® 6-25, 6-27 
START_POSITION qualifier ® 2-6 
STARTCOLUMN option ® 2-54 
Start-up command file ® 2-59 
Subfields ® 6-18 
SUB operation code ® 16-3 
example ® 16-5 
Subprogram operation codes ® 16-31 
CALL ® 16-32 
EXTRN ® 16-32 
GIVNG ® 16-33 
PARM ® 16-33 
PARMD ® 16-34 
PARMV ® 16-35 
PLIST © 16-35 
Subprograms ® 12-32 
calling ® 16-32 
example ® 12-32 
parameter list ® 16-35 
PARM ® 16-33 . 
passing parameters ® 16-33, 16-34, 16-35 
PLIST ® 16-35 
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Subroutines 
executing ® 16-12 
marking the beginning ® 16-12 
marking the ending ® 16-12 
names ® 14-8 
operation codes ® 16-11 
BEGSR ® 16-12 
ENDSR ® 16-12 
example ® 16-13 
EXSR ® 16-12 
Subtraction operation ® 16-3 
Symbolic device ® 15-39 
SYNTAXCHECK option ® 2-55 
SYSTEM ® 5-12 
System routines ® 12-1 
determining the type of call 
function ® 12-6 
procedure ® 12-6 
examples of calling ® 12-25 
function calls ® 12-17 
function results ® 12-24 
how to call ® 12-4 
passing mechanisms ® 12-13 
procedure calls ® 12-20 © 
procedure results ® 12-25 
System services ® 12-28 
calling ® 16-32 
example ® 12-29, 12-30, 12-31 
determining the type of call 
function ® 12-6 
‘procedure ® 12-6 
groups ® 12-3 
how to call ® 12-4 
passing parameters ® 16-33, 16-34, 16-35 
routines ® 12-3 
symbolic constants 
example ® 12-24 
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TAB function 
example ® 2-68 to 2-70 
Table or array name ® 15-53 
rules for specifying ® 15-53 
Tables ® 10-1 
alternate format ® 15-59 
compile-time ® 10-2 
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compile-time (cont’d.) 
rules for defining ® 10-7 
creating 
input records ® 10-3 
definition ® 10-1 
entries © 10-3 
input records ® 10-3 
creating ® 10-3 
example ® 10-4 
rules for specifying ® 10-3 
loading time 
selecting ® 10-1 
LOKUP operation code ® 10-10, 16-28 
names ® 14-8 
outputting 
example ® 10-14 
preexecution-time ® 10-3 
rules for defining ® 10-8 
referencing entries ® 10-9 
example ® 10-9 
related ® 10-1, 10-4 
creating ® 10-4 
example ® 10-7 
example ® 10-12 
updating ® 10-12 
searching ® 10-10, 16-28 
example ® 16-30 
rules for specifying ® 10-10 
single © 10-1 
defining ® 10-5 
compile-time ® 10-6 
example ® 10-6, 10-7 
preexecution-time ® 10-8 
specifying ® 15-22 
alternate format ® 15-59 
current entry ® 10-9 
example ® 10-10 
data format ® 15-56 
decimal positions ® 15-57 
from file name ® 15-51 
length of entry ® 15-55 
names ® 15-53 
number of entries per record ® 15-54 


number of entries per table or array ® | 


15-55 
sequence ® 10-11, 15-58 
ascending ® 10-11 


Tables 
specifying 
sequence (cont’d.) 
descending ® 10-11 
example ® 10-12 
to file name ® 15-52 
updating ® 10-12 
writing ® 10-14 
Tab stops ® 2-6 
definition ® 2-9 
TAG operation code ® 16-26 
example ® 16-27 
rules ® 16-26 
Tapes 
rewinding ® 15-47 
specifying 
labels ® 15-40 
ANSI ® 15-40 
TDMS ® 12-33 
Terminal device 
specifying ® 15-38 
TESTB operation code ® 16-14 
example ® 16-15 
rules ® 16-14, 16-15 
Time 
printing ® 9-6 
TIME operation code ® 16-36 
To file name 
outputting 
arrays ® 15-52 
tables ® 15-52 
record-address files ® 15-52 
rules for specifying ® 15-52 
writing 
arrays ® 15-52 
tables ® 15-52 
TOP function ® 2-25 
Total time ® 1-8 
Total-time characteristics or operations ® 1-5 
Type ® 15-113 


UAR 
function key ® 6-13 
linking © 6-14 
object file © 6-14 
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UDATE special word ® 9-4 
defining ® 9-4 
editing * 9-4 
specifying notation ® 15-14 
UNDELETE _FIELD function ® 2-24 
UNDELETE_LINE function ® 2-21 
Unordered output ® 15-42 
rules for specifying ® 15-43 
Update files 
selecting mode of processing ® 15-29 
specifying 
file addition ® 15-42 
unordered output ® 15-42 
Updating 
files © 8-31 
randomly by. key ® 8-34 
sequentially ® 8-34 
records ® 8-31 
example ® 8-32 
UP function ® 2-33 
example ® 2-85 
User-defined command keys ® 6-12 
User-defined names ® 14-8 
rules ® 14-9 
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VAX/VMS10 Usages 
VAX RPG II equivalents ® 12-9 
VAX/VMS Modular Programming Standard ® 
12-32 
VAX/VMS Run-Time Library parameter access 
types. 
modify ® 12-15 
read only ® 12-15 
write only ® 12-15 
example ® 12-15 . 
VAX/VMS Run-Time Library parameter data types 
double precision floating point ® 12-15 
longword integer ® 12-15 
numeric string © 12-16 
example ® 12-16 
packed decimal string ® 12-16 
quadword integer ® 12-15 
single precision floating point ® 12-15 
text string ® 12-15 
word integer ® 12-15 
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VAX/VMS Run-Time Library parameter passing 
mechanisms 
by descriptor 
' example ® 12-13 
by reference. 
example ® 12-8, 12-13 
by value ® 12-12, 12-19 
example ® 12-12, 12-19 . 
VAX/VMS Run-Time Library procedures 
assigning names ® 16-32 
calling ® 16-32 
example ® 12-5, 12-6, 12-18, 12-19, 
12-26, 12-27, 12-28 
GIVNG operation code ® 16-33 
parameter characteristics 
access types ® 12-15 
data types ® 12-15 
passing mechanisms ® 12-12 
parameter passing mechanisms 
by descriptor ® 12-12 
PARMD operation code ® 12-12 
by reference ® 12-12 
PARM operation code ® 12- 12 
by value ® 12-12 
example ® 12-12, 12-19 
PARMV operation code ® 12-12 
passing parameters ® 16-33, 16-34, 16-35 
VAX/VMS Run-Time Library routines 
arguments 
optional ® 12-7 
required ® 12-7 
VAX/VMS Usages ® 12-9 
VAX FMS ® 12-33, 12-36 
editor ® 6-2 . 
form creation ® 6-2 
form libraries ® 6-3 
multiple forms ® 6-3 
WORKSTHN file interface ® 6-1 
VAX Procedure Calling and Condition Handling 
Standard ® 12-32 
VAX RPG Il . 
differences between PDP-11 RPG II ®B-1 
different support ® B-2 
editor — 
non-supported functionality ® B-7 
new functionality © B-5 
non-supported functionality ® B-1 
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new functionality ® B-5 
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auto right justification of numeric fields © 2-55 
blinking the current column ® 2-32 
buffers ® 2-11 _ 
current ® 2-11 
deleted-field ® 2-11 
deleted-line ® 2-11 
paste © 2-11 
compiling programs ® 2-36 
creating 
a new program line ® 2-32, 2-34 
programs _ 
example ® 2-62 to 2-63 
creating files ® 2-4 
cursor ® 2-10 | 
customizing ® 2-59. 
editor commands ® 2-59 
example ® 2-60 
start-up command file & 2-59 
. SET COMMAND option ® 2-59 
deleting 
a character and shifting the program line 
left ® 2-26 
a character and shifting the program line 
right © 2-27 
characters from the cursor to the end of 
the line ® 2-30 
fields ® 2-24 
determining where the editor starts © 2-6 
displaying - 
current column setting ® 2-56 
current DEFAULT setting ® 2-56 
current SCROLL setting ® 2-56 
current SECTION setting ® 2-56 
current SYNTAXCHECK setting ® 2-56 
HELP information ¢ 2-43 
program ® 2-23 
version number and copyright ® 2-57 
editing an existing program 
example ® 2-77 ' 
finding the next error ® 2-23 
functions 
displaying HELP information ® 2-15 
inserting the contents of the paste buffer ® 2-26 
invoking ® 2-1, 2-64, 2-77 
example ® 2-65, 2-77 
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keypad ® 2-12 
displaying - 
keypad diagram © 2-15 
example ® 2-12 
naming conventions ® 2- 12 
leaving the editor ® 2-41, 2-47 
moving 
current line ® 2- 32 
current line to the ruler ® 2-24 — 
sections of the editing buffer © 2-23 
moving cursor 
backward ® 2-25 
down ® 2-33 
left © 2-34 
right © 2-34 
to end of a program line ® 2- 29 
to first line ® 2-25 
to last line ® 2-25 
to next character ® 2-31 
to next field ® 2-28 
to next tab stop ® 2-35 
to preceding tab stop ® 2-34 
up ® 2-33 
naming the output file ® 2-4, 2- 5 
numbering program lines ® 2-49 
overstriking © 2-1 
placing selected text into the paste buffer ® 
2-26 
qualifiers ® 2-1 to 2-6 
recovering edits ® 2-5 
renumbering existing program lines ® 2-49 
replacing 
the preceding character with a space ® 
2-34 
the program line with spaces ® 2-35 
resetting the select range ® 2-33 
rewriting the screen display ® 2-35 
saving edits ® 2-4 
screen ® 2-6. 
selecting a range of lines for the paste buffer ® 
2-33 
setting 
terminal characters ® 2-12 
the current direction forward ® 2-25 
the location of the ruler ® 2-51 
the number of display lines ® 2-54 
the scroll region ® 2-53 


Index-27 


VAX RPG II editor (cont’d.) 


single line syntax check ® 2-55 

specifying the current column ® 2-54 

start-up command ® 2-3 

terminating VAX RPG Il editor command entries 
© 2-32 

undeleting fields © 2-24 

viewing programs ® 2-5 

VK 100 (GIGI!) terminal © 2-6 

writing the editing buffer to an output file © 2-35 
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COMPILE ® 2-36 
DEFINE KEY ® 2-38 
EXIT @ 2-41 
example ® 2-42 
SAVE qualifier ® 2-42 
HELP ® 2-43 
example ® 2-44 
INCLUDE ® 2-47 
QUIT ® 2-47 
example ® 2-48 
SAVE qualifier ® 2-49 
RESEQUENCE ® 2-49 
example ® 2-82 
options ® 2-49 
_ REMOVE ® 2-48 
SET ® 2-50 
format ® 2-50 
options 
COMMAND ® 2-50 
HELP KEYPAD ® 2-51 
HELP NONE ® 2-51 
HELP SPECIFICATIONS ® 2-51 
RULER ® 2-51 
SCROLL ® 2-53 
SECTION ® 2-54 
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80-column ruler ® 2-6 
definition ® 2-9 
example ® 2-6, 2-8 
displaying HELP information ® 2-7 
editing window ® 2-6 
example ® 2-8 
EOB mark®2-9 
HELP window ® 2-6 
displaying HELP information ® 2-7 
example ® 2-6 
message line ® 2-6 
definition ® 2-9 
example ® 2-6, 2-8, 2-10 
prompt line ® 2-6 
definition ® 2-9 
example ® 2-6, 2-10 
source window 
example ® 2-6 
specification format 
example ® 2-10 
tab stops ® 2-6 
definition ® 2-9 
example ® 2-6, 2-8 
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S and Display specification ® 6-31 


VAX RPG II programs 


compiling ® 3-1 
creating ® 2-1 
debugging ® 5-1 
developing ® 3-1 
editing ® 2-1 

linking ® 3-11 . 
optimizing ® 13-1 
running ® 3-12 
viewing ® 2-1 


STARTCOLUMN ® 2-54 
SYNTAXCHECK ® 2-55 
SHOW ® 2-56 
options 
DEFAULT ® 2-56 W 
SCROLL ® 2-56 
SECTION ® 2-56 
STARTCOLUMN ® 2-56 
SYNTAXCHECK ® 2-56 
VERSION ® 2-57 
SUBSTITUTE ® 2-57 
Rules for specification ® 2-58 


VAX SMG$§ ® 12-33 
VAX TDMS ® 12-33 





WARNINGS qualifier 
displaying 
error messages ® 3-10 
information messages ® 3-11 
format ® 3-10 
options ® 3-10 
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WARNINGS qualifier 
options (cont’d.) 
INFORMATION ® 3-10 
OTHER ® 3-10 
Word binary data type 
example ® 14-4 
WORKSTN 
calculation specifications ® 6-5 
EOF detection ® 6-6 
file ® 6-1, 6-3 
designation ® 6-5 
operation status code ® 6-17 
specifications ® 6-4 
input specifications ® 6-5 
output specifications ® 6-7 
primary file ® 6-6 
run-time support 
current workspace ® 6-9 
form display ® 6-8 
form read ® 6-9 
initialization ® 6-8 
termination ® 6-9 
VAX FMS forms interface ® 6-1 
VAX FMS run-time support ® 6-7 
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XFOOT operation code ® 16-5 
arrays ® 11-16 
example ® 11-17 
referencing array elements ® 11-17 
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Z-ADD operation code ® 16-3 
example ® 16-5 

Zero-suppression ® 15-139 

Z-SUB operation code ® 16-3 
example ® 16-5 
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